ui-engine-xin 0.0.1__py3-none-any.whl

UIEngine/__init__.py

@@ -0,0 +1,9 @@
+"""UIEngine - 基于 Playwright 的关键字驱动 UI 自动化测试引擎"""
+__version__ = "0.0.1"
+
+from UIEngine.basecase import BaseCase
+from UIEngine.core.keyword_manager import KeyWordManager
+from UIEngine.core.variable_resolver import VariableResolver
+from UIEngine.runner.runner import Runner
+from UIEngine.reporting.result import TestResult
+from UIEngine.caseLog import CaseLogHandler

UIEngine/basecase.py

@@ -0,0 +1,60 @@
+"""BaseCase 组合类
+
+将所有 Mixin 组合为统一的测试用例基类。
+包含关键字调度（perform）和变量替换功能。
+所有 Mixin 方法在类定义后自动注册到 KeyWordManager。
+"""
+from UIEngine.browser.base_browser import BaseBrowser
+from UIEngine.keywords.page_keywords import PageMixin
+from UIEngine.keywords.locator_keywords import LocatorMixin
+from UIEngine.keywords.mouse_keywords import MouseMixin
+from UIEngine.keywords.wait_keywords import WaitMixin
+from UIEngine.keywords.iframe_keywords import IFrameMixin
+from UIEngine.keywords.assert_keywords import AssertMixin
+from UIEngine.core.keyword_manager import KeyWordManager
+from UIEngine.core.variable_resolver import VariableResolver
+from UIEngine.core.exceptions import KeywordNotFoundError
+
+
+class BaseCase(PageMixin, LocatorMixin, MouseMixin, WaitMixin, IFrameMixin, AssertMixin):
+    """测试用例基类 - 组合所有关键字 Mixin
+
+    继承链（MRO）：
+    BaseCase → PageMixin → LocatorMixin → MouseMixin → WaitMixin
+             → IFrameMixin → AssertMixin → BaseBrowser
+    """
+
+    def __init__(self, config, log, **kwargs):
+        super().__init__(config, log, **kwargs)
+        self.variable_resolver = VariableResolver(config, log)
+
+    def perform(self, step):
+        """执行测试步骤
+
+        支持两种执行模式：
+        1. 关键字模式：通过 KeyWordManager.maps 查表调用（step 中使用 "keyword" 或 "method"）
+        2. 直接调用模式：关键字未注册时，回退到 getattr(self, method) 直接调用
+
+        模式 2 允许调用未注册为关键字的实例方法（如 open_browser, close, reset_browser_context 等）。
+
+        :param step: 测试步骤字典，包含 keyword/method、params、desc 等字段
+        """
+        keyword = step.get("keyword") or step.get("method")
+        # 优先通过关键字注册表查找
+        method = KeyWordManager.get_keyword_maps(keyword)
+        if method:
+            params = step.get("params", {})
+            params = self.variable_resolver.resolve(params)
+            method(self, **params)
+        elif hasattr(self, keyword):
+            # 回退：直接调用实例方法（兼容未注册为关键字的方法）
+            params = step.get("params", {})
+            params = self.variable_resolver.resolve(params)
+            getattr(self, keyword)(**params)
+        else:
+            raise KeywordNotFoundError(f"{step.get('desc', '')}执行的关键字 '{keyword}' 不存在")
+
+
+# 自动注册：将 BaseCase 的所有公共方法注册到关键字映射表
+# 已通过 @register 装饰器注册的方法不会被覆盖
+KeyWordManager.auto_register_methods(BaseCase)

UIEngine/browser/__init__.py

@@ -0,0 +1,2 @@
+"""浏览器管理模块"""
+from UIEngine.browser.base_browser import BaseBrowser

UIEngine/browser/base_browser.py

@@ -0,0 +1,158 @@
+"""浏览器生命周期管理
+
+包含：浏览器创建/关闭、上下文管理、多页面管理。
+修复：self.pages 未初始化、headless 逻辑反转。
+新增：上下文管理器（__enter__/__exit__）。
+"""
+import re
+from playwright.sync_api import sync_playwright
+
+
+class BaseBrowser:
+    """浏览器基类：管理 browser/context/page 三层对象"""
+
+    def __init__(self, config, log, browser=None, context=None, page=None):
+        """
+        :param config: 环境配置字典
+        :param log: 日志处理器
+        :param browser: 可选，复用的浏览器实例
+        :param context: 可选，复用的上下文实例
+        :param page: 可选，复用的页面实例
+        """
+        self.config = config
+        self.log = log
+        self.pw = None
+        self.browser = None
+        self.context = None
+        self.page = None
+        self.pages = {}  # 修复：初始化 pages 字典
+        self._current_frame = None  # iframe 上下文状态
+        # 三个对象全部存在才复用
+        if all([browser, context, page]):
+            self.browser = browser
+            self.context = context
+            self.page = page
+            self.pages['default'] = self.page
+
+    def __getattr__(self, item):
+        """当浏览器没有创建时，自动创建浏览器"""
+        if item in ["browser", "context", "page"]:
+            self.log.debug_log(f"当前浏览器没有启动，{item}属性不存在，正在为您启动浏览器")
+            self.open_browser(self.config.get("browser_type"))
+            return getattr(self, item)
+        else:
+            raise AttributeError(f"{item}属性不存在")
+
+    def __enter__(self):
+        """上下文管理器入口"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """上下文管理器出口：确保浏览器资源被释放"""
+        try:
+            self.close()
+        except Exception:
+            pass
+        return False
+
+    def open_browser(self, browser_type):
+        """打开浏览器"""
+        browser_type = browser_type or self.config.get("browser_type")
+        self.browser, self.context, self.page = self.create_browser(browser_type)
+        self.pages['default'] = self.page
+        self.log.debug_log("打开浏览器成功")
+
+    def create_browser(self, browser_type):
+        """创建浏览器对象"""
+        # 1. 启动 Playwright 运行时核心
+        self.pw = sync_playwright().start()
+        # 2. 动态获取浏览器启动器（chromium/firefox/webkit）
+        browser_type_obj = getattr(self.pw, browser_type)
+        # 3. 启动浏览器实例（修复：is_debug=True 时显示浏览器窗口）
+        browser = browser_type_obj.launch(headless=not self.config.get("is_debug", False))
+        # 4. 创建隔离浏览器上下文（独立会话环境）
+        context = browser.new_context()
+        # 5. 创建页面 Tab（对应浏览器标签页）
+        page = context.new_page()
+        # 6. 返回三层对象
+        return browser, context, page
+
+    def reset_browser_context(self):
+        """重置浏览器运行环境：清除 cookie 和浏览器的缓存信息"""
+        self.page.close()
+        self.context.close()
+        self.context = self.browser.new_context()
+        self.page = self.context.new_page()
+
+    def close(self):
+        """关闭浏览器"""
+        try:
+            if self.page:
+                self.page.close()
+            if self.context:
+                self.context.close()
+            if self.browser:
+                self.browser.close()
+            if self.pw:
+                self.pw.stop()
+        except Exception:
+            pass
+
+    def open_new_page(self, tag, timeout=3000):
+        """
+        打开新页面
+        :param tag: 页面标签
+        :param timeout: 超时时间
+        """
+        self.pages[tag] = self.context.new_page()
+        self.log.debug_log("页面已经打开")
+
+    def find_page(self, tag='', index='', title='', url=''):
+        """查找页面
+
+        :param tag: 页面标签
+        :param index: 页面索引
+        :param title: 页面标题
+        :param url: 页面 URL（支持正则匹配）
+        :return: 匹配的页面对象
+        """
+        if tag:
+            return self.pages[tag]
+        elif index:
+            return self.context.pages[int(index)]
+        elif title:
+            for page in self.context.pages:
+                if page.title() == title:
+                    return page
+        elif url:
+            for page in self.context.pages:
+                if re.search(url, page.url):
+                    return page
+        else:
+            return self.context.pages[-1]
+
+    def switch_to_page(self, tag='', index='', title='', url=''):
+        """
+        切换到指定页面：默认切换到最新的窗口页面
+        :param tag: 页面标签
+        :param index: 页面打开的顺序
+        :param title: 页面标题
+        :param url: 页面的 url
+        """
+        page = self.find_page(tag, index, title, url)
+        self.page = page
+
+    def close_page(self, tag='', index='', title='', url=''):
+        """
+        关闭页面：默认关闭最新打开的页面
+        :param tag: 页面标签
+        :param index: 页面打开的顺序
+        :param title: 页面标题
+        :param url: 页面的 url
+        """
+        page = self.find_page(tag, index, title, url)
+        if page == self.page and len(self.context.pages) > 1:
+            page.close()
+            self.page = self.context.pages[0]
+        else:
+            page.close()

UIEngine/caseLog.py

@@ -0,0 +1,145 @@
+"""用例日志处理类
+
+基于 Python 标准 logging 模块实现，对外接口与原版完全兼容。
+- log_data 属性保持 [(level, msg), ...] 格式
+- debug_log/info_log/warning_log/error_log 等方法名不变
+- 支持日志级别过滤、文件输出等 logging 原生能力
+"""
+import logging
+import os
+import time
+from pathlib import Path
+
+
+class _MemoryHandler(logging.Handler):
+    """内存日志 Handler：将日志记录存储为兼容原有格式的列表"""
+
+    def __init__(self):
+        super().__init__()
+        self.log_data = []
+
+    def emit(self, record):
+        ts = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(record.created))
+        msg = f"{ts} | {record.getMessage()}"
+        self.log_data.append((record.levelname, msg))
+
+
+class CaseLogHandler:
+    """用例日志处理类（基于 logging 模块）
+
+    对外接口与原版完全兼容：
+    - debug_log / info_log / warning_log / error_log / critical_log / print_log
+    - log_data 属性返回 [(level, msg), ...] 列表
+    """
+
+    def __init__(self, name="testcase", console=True, level=logging.DEBUG):
+        """
+        :param name: logger 名称（不同用例建议使用不同名称避免日志混合）
+        :param console: 是否输出到控制台
+        :param level: 最低日志级别
+        """
+        self._logger = logging.getLogger(name)
+        self._logger.setLevel(level)
+        # 避免重复添加 handler（同名 logger 多次实例化时）
+        if not self._logger.handlers:
+            # 内存 Handler（用于结果数据收集）
+            self._memory = _MemoryHandler()
+            self._logger.addHandler(self._memory)
+            # 控制台 Handler（用于实时输出）
+            if console:
+                console_handler = logging.StreamHandler()
+                console_handler.setFormatter(
+                    logging.Formatter("%(levelname)s | %(message)s")
+                )
+                self._logger.addHandler(console_handler)
+        else:
+            # 复用已有 handler，找到 memory handler
+            self._memory = next(
+                (h for h in self._logger.handlers if isinstance(h, _MemoryHandler)),
+                _MemoryHandler()
+            )
+
+    @property
+    def log_data(self):
+        """兼容 Runner 中 getattr(self.log, 'log_data') 的访问方式"""
+        return self._memory.log_data
+
+    def _format_args(self, args):
+        """将可变参数拼接为字符串"""
+        return " ".join(str(i) for i in args)
+
+    def debug_log(self, *args):
+        """记录 debug 日志"""
+        self._logger.debug(self._format_args(args))
+
+    def info_log(self, *args):
+        """记录 info 日志"""
+        self._logger.info(self._format_args(args))
+
+    def warning_log(self, *args):
+        """记录 warning 日志"""
+        self._logger.warning(self._format_args(args))
+
+    def error_log(self, *args):
+        """记录 error 日志"""
+        self._logger.error(self._format_args(args))
+
+    def critical_log(self, *args):
+        """记录 critical 日志"""
+        self._logger.critical(self._format_args(args))
+
+    def print_log(self, *args):
+        """记录日志（等同 info 级别）"""
+        self._logger.info(self._format_args(args))
+
+    def add_file_handler(self, filepath=None, level=logging.DEBUG, max_files=20):
+        """添加文件输出 Handler
+
+        :param filepath: 日志文件路径（默认保存到 UIEngine/files/logs/<name>_<timestamp>.log）
+        :param level: 文件日志的最低级别
+        :param max_files: 日志文件最大保留数量（默认 20）
+        """
+        if not filepath:
+            engine_root = Path(__file__).resolve().parent
+            log_dir = engine_root / "files" / "logs"
+            log_dir.mkdir(parents=True, exist_ok=True)
+            ts = time.strftime("%Y%m%d_%H%M%S", time.localtime())
+            filepath = str(log_dir / f"{self._logger.name}_{ts}.log")
+            # 清理超出限制的旧日志文件
+            self._cleanup_log_files(str(log_dir), max_files)
+
+        file_handler = logging.FileHandler(filepath, encoding='utf-8')
+        file_handler.setLevel(level)
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+        )
+        self._logger.addHandler(file_handler)
+
+    @staticmethod
+    def _cleanup_log_files(log_dir, max_files):
+        """清理旧日志文件，保留最新的 max_files 个"""
+        files = []
+        for entry in os.listdir(log_dir):
+            if entry.endswith('.log'):
+                full_path = os.path.join(log_dir, entry)
+                files.append((full_path, os.path.getmtime(full_path)))
+        files.sort(key=lambda x: x[1], reverse=True)
+        for old_file, _ in files[max_files:]:
+            try:
+                os.remove(old_file)
+            except OSError:
+                pass
+
+    def set_level(self, level):
+        """动态调整日志级别（logging 新增能力）
+
+        :param level: logging.DEBUG / logging.INFO / logging.WARNING 等
+        """
+        self._logger.setLevel(level)
+
+
+class PreconditionChainError(Exception):
+    """前置条件链执行错误（用于 stop 模式中止）"""
+    def __init__(self, errors):
+        self.errors = errors
+        super().__init__(f"前置条件链中止，共 {len(errors)} 个错误")

UIEngine/config/__init__.py

@@ -0,0 +1 @@
+"""配置模块"""

UIEngine/config/default.yaml

@@ -0,0 +1,6 @@
+# UI 自动化测试引擎默认配置
+browser_type: chromium
+is_debug: false
+host: ""
+max_suite_screenshot_dirs: 10
+global_variable: {}

UIEngine/core/__init__.py

@@ -0,0 +1,4 @@
+"""核心模块：关键字管理、变量解析、自定义异常"""
+from UIEngine.core.keyword_manager import KeyWordManager
+from UIEngine.core.variable_resolver import VariableResolver
+from UIEngine.core.exceptions import KeywordNotFoundError

UIEngine/core/exceptions.py

@@ -0,0 +1,9 @@
+"""自定义异常类"""
+
+
+class KeywordNotFoundError(AttributeError):
+    """关键字未找到异常
+
+    当 perform() 在 KeyWordManager.maps 和实例方法中都找不到对应的关键字时抛出。
+    """
+    pass

UIEngine/core/keyword_manager.py

@@ -0,0 +1,109 @@
+"""关键字管理器：维护关键字名称与函数的映射关系
+
+支持功能：
+- 装饰器注册（中英文双名）
+- 动态字符串代码注册
+- 大小写兼容查找
+- 自动注册类方法
+"""
+import inspect
+
+
+class KeyWordManager:
+    """关键字的映射关系管理"""
+    maps = {}
+
+    @classmethod
+    def register(cls, *keywords):
+        """装饰器注册关键字，支持同时注册中英文名称
+
+        用法示例：
+            @KeyWordManager.register("click_element", "点击元素")
+            def click_element(self, locator, timeout=3000):
+                ...
+
+        :param keywords: 一个或多个关键字名称（建议：英文在前，中文在后）
+        :return: 装饰器函数
+        """
+        def wrapper(func):
+            for kw in keywords:
+                cls.maps[kw] = func
+            return func
+        return wrapper
+
+    @classmethod
+    def register_keyword(cls, keywords, func_code):
+        """动态注册关键字（从字符串代码）
+
+        :param keywords: str 或 list[str]，一个或多个关键字名称
+        :param func_code: 字符串形式的函数定义代码
+        :return: None
+
+        用法示例：
+            KeyWordManager.register_keyword(
+                ["open_browser", "打开浏览器"],
+                '''
+def open_browser(self, browser_type):
+    print(f"打开{browser_type}浏览器")
+                '''
+            )
+        """
+        if isinstance(keywords, str):
+            keywords = [keywords]
+        temp_map = {}
+        exec(func_code, temp_map)
+        for k, v in temp_map.items():
+            if inspect.isfunction(v):
+                for kw in keywords:
+                    cls.maps[kw] = v
+                # 动态挂载到 BaseCase 类（延迟导入避免循环依赖）
+                from UIEngine.basecase import BaseCase
+                setattr(BaseCase, k, v)
+
+    @classmethod
+    def get_keyword_maps(cls, keyword):
+        """查找关键字对应的函数，支持大小写兼容
+
+        :param keyword: 关键字名称
+        :return: 对应的函数对象，未找到返回 None
+        """
+        if keyword is None:
+            return None
+        # 精确匹配优先
+        result = cls.maps.get(keyword)
+        if result is not None:
+            return result
+        # 大小写不敏感兜底匹配
+        return cls.maps.get(keyword.lower())
+
+    @classmethod
+    def auto_register_methods(cls, target_class):
+        """自动注册目标类的所有公共方法到关键字映射表
+
+        用于在 BaseCase 定义完成后，将所有 Mixin 方法自动注册到 maps 中。
+        已通过 @register 装饰器注册的方法不会被覆盖。
+
+        :param target_class: 要扫描注册的类
+        """
+        # 不需要注册为关键字的内部方法列表
+        excluded = {
+            'perform', 'replace_params', 'close', 'open_browser',
+            'create_browser', 'reset_browser_context', 'find_page',
+            'switch_to_page', 'close_page',
+            'save_page_img',
+        }
+        for name, method in inspect.getmembers(target_class, predicate=inspect.isfunction):
+            if name.startswith('_'):
+                continue
+            if name in excluded:
+                continue
+            if name not in cls.maps:
+                cls.maps[name] = method
+
+    @classmethod
+    def list_keywords(cls):
+        """列出所有已注册的关键字
+
+        :return: 关键字名称列表
+        """
+        return list(cls.maps.keys())

UIEngine/core/variable_resolver.py

@@ -0,0 +1,74 @@
+"""变量解析器：处理参数中的 ${variable} 占位符替换
+
+采用递归遍历数据结构的方式，直接替换字符串值中的变量，
+避免 str(dict) + literal_eval 导致的特殊字符解析崩溃问题。
+"""
+import re
+
+
+class VariableResolver:
+    """解析参数中的变量占位符 ${var_name}
+
+    从 config["global_variable"] 字典中查找变量值并替换。
+    递归遍历 dict/list/str，保持原始数据结构不变。
+    """
+
+    _pattern = re.compile(r'\$\{(.+?)\}')
+
+    def __init__(self, config, log):
+        """
+        :param config: 配置字典，包含 global_variable 字段
+        :param log: 日志处理器实例
+        """
+        self.config = config
+        self.log = log
+
+    def resolve(self, value):
+        """替换参数中的变量占位符，保持原始数据结构
+
+        :param value: 要进行变量替换的参数（dict / list / str / 其他）
+        :return: 替换后的参数，类型与输入保持一致
+        """
+        if isinstance(value, dict):
+            return {k: self.resolve(v) for k, v in value.items()}
+        if isinstance(value, list):
+            return [self.resolve(item) for item in value]
+        if isinstance(value, str):
+            return self._resolve_string(value)
+        return value
+
+    def _resolve_string(self, text):
+        """替换单个字符串中的变量占位符
+
+        处理逻辑：
+        - 如果整个字符串就是一个占位符 ${var}，且变量值是非字符串类型，
+          直接返回原始类型（int/float/bool/list/dict），保持类型不变
+        - 如果字符串包含多个占位符或混合文本，变量值统一转为字符串拼接
+
+        :param text: 包含 ${var} 占位符的字符串
+        :return: 替换后的值（可能是 str，也可能是变量的原始类型）
+        """
+        # 快速检查：字符串中是否包含占位符
+        if '${' not in text:
+            return text
+
+        # 特殊情况：整个字符串就是单个占位符，保留变量原始类型
+        match = self._pattern.fullmatch(text.strip())
+        if match:
+            key = match.group(1)
+            var_value = self.config.get('global_variable', {}).get(key)
+            if var_value is not None:
+                return var_value
+            self.log.debug_log(f"测试环境中全局变量中没有：{key}这个变量")
+            return text
+
+        # 通用情况：字符串中混合了文本和占位符，统一替换为字符串
+        def _replacer(m):
+            key = m.group(1)
+            var_value = self.config.get('global_variable', {}).get(key)
+            if var_value is not None:
+                return str(var_value)
+            self.log.debug_log(f"测试环境中全局变量中没有：{key}这个变量")
+            return m.group(0)
+
+        return self._pattern.sub(_replacer, text)

UIEngine/keywords/__init__.py

@@ -0,0 +1,7 @@
+"""关键字模块：封装所有 Playwright 操作的关键字实现"""
+from UIEngine.keywords.page_keywords import PageMixin
+from UIEngine.keywords.locator_keywords import LocatorMixin
+from UIEngine.keywords.mouse_keywords import MouseMixin
+from UIEngine.keywords.wait_keywords import WaitMixin
+from UIEngine.keywords.assert_keywords import AssertMixin
+from UIEngine.keywords.iframe_keywords import IFrameMixin