kdtest-pw 2.0.0__py3-none-any.whl

kdtest_pw/cases/read/excel_reader.py

@@ -0,0 +1,223 @@
+"""Excel 测试用例解析器"""
+
+from typing import List, Dict, Any, Optional, Tuple
+from pathlib import Path
+
+from ...reference import INFO
+from ...common import EXCEL_COLUMNS
+
+
+class ExcelReader:
+    """Excel 测试用例读取器
+
+    兼容原 kdtest Excel 格式，解析测试用例文件。
+    """
+
+    def __init__(self, file_path: str):
+        """初始化 Excel 读取器
+
+        Args:
+            file_path: Excel 文件路径
+        """
+        self._file_path = Path(file_path)
+        self._workbook = None
+        self._sheets: List[str] = []
+
+        if not self._file_path.exists():
+            raise FileNotFoundError(f"Excel 文件不存在: {file_path}")
+
+        self._load_workbook()
+
+    def _load_workbook(self) -> None:
+        """加载工作簿"""
+        try:
+            import openpyxl
+            self._workbook = openpyxl.load_workbook(str(self._file_path), data_only=True)
+            self._sheets = self._workbook.sheetnames
+            INFO(f"加载 Excel: {self._file_path.name}, Sheets: {self._sheets}")
+        except ImportError:
+            raise ImportError("请安装 openpyxl: pip install openpyxl")
+
+    @property
+    def sheet_names(self) -> List[str]:
+        """获取所有 Sheet 名称"""
+        return self._sheets.copy()
+
+    def read_sheet(self, sheet_name: str) -> List[Dict[str, Any]]:
+        """读取指定 Sheet 的测试用例
+
+        Args:
+            sheet_name: Sheet 名称
+
+        Returns:
+            List[Dict]: 测试用例列表
+        """
+        if sheet_name not in self._sheets:
+            raise ValueError(f"Sheet 不存在: {sheet_name}")
+
+        sheet = self._workbook[sheet_name]
+        cases = []
+        current_case = None
+        steps = []
+
+        for row_idx, row in enumerate(sheet.iter_rows(min_row=1, values_only=True), start=1):
+            # 跳过空行
+            if not any(row):
+                continue
+
+            # 获取各列值
+            case_id = self._get_cell_value(row, 0)
+            case_name = self._get_cell_value(row, 1)
+            description = self._get_cell_value(row, 2)
+            keyword = self._get_cell_value(row, 3)
+
+            # 获取定位信息 (E-N 列，索引 4-13)
+            locator_info = []
+            for i in range(4, 14):
+                val = self._get_cell_value(row, i)
+                if val:
+                    locator_info.append(val)
+
+            # 获取操作值 (O 列，索引 14)
+            value = self._get_cell_value(row, 14)
+
+            # 判断是否是用例开始行
+            if case_id or case_name:
+                # 保存上一个用例
+                if current_case and steps:
+                    current_case['steps'] = steps
+                    cases.append(current_case)
+
+                # 开始新用例
+                current_case = {
+                    'id': case_id or f"case_{len(cases) + 1}",
+                    'name': case_name or f"用例{len(cases) + 1}",
+                    'sheet': sheet_name,
+                    'row': row_idx,
+                    'steps': []
+                }
+                steps = []
+
+                # 如果当前行有关键字，也作为第一个步骤
+                if keyword:
+                    steps.append({
+                        'row': row_idx,
+                        'description': description,
+                        'keyword': keyword,
+                        'locator': locator_info,
+                        'value': value
+                    })
+            elif keyword:
+                # 步骤行
+                steps.append({
+                    'row': row_idx,
+                    'description': description,
+                    'keyword': keyword,
+                    'locator': locator_info,
+                    'value': value
+                })
+
+        # 保存最后一个用例
+        if current_case and steps:
+            current_case['steps'] = steps
+            cases.append(current_case)
+
+        INFO(f"读取 {sheet_name}: {len(cases)} 个用例")
+        return cases
+
+    def read_all_sheets(self, include_sheets: List[str] = None) -> Dict[str, List[Dict[str, Any]]]:
+        """读取所有或指定 Sheet 的测试用例
+
+        Args:
+            include_sheets: 要包含的 Sheet 列表，None 表示全部
+
+        Returns:
+            Dict[sheet_name, cases]: Sheet 名称到用例列表的映射
+        """
+        result = {}
+        sheets_to_read = include_sheets or self._sheets
+
+        for sheet_name in sheets_to_read:
+            if sheet_name in self._sheets:
+                result[sheet_name] = self.read_sheet(sheet_name)
+
+        return result
+
+    def _get_cell_value(self, row: tuple, index: int) -> Optional[str]:
+        """获取单元格值
+
+        Args:
+            row: 行数据
+            index: 列索引
+
+        Returns:
+            单元格值（字符串）
+        """
+        if index >= len(row):
+            return None
+
+        value = row[index]
+        if value is None:
+            return None
+
+        return str(value).strip()
+
+    def get_case_count(self, sheet_name: str = None) -> int:
+        """获取用例数量
+
+        Args:
+            sheet_name: Sheet 名称，None 表示全部
+
+        Returns:
+            int: 用例数量
+        """
+        if sheet_name:
+            return len(self.read_sheet(sheet_name))
+
+        total = 0
+        for sheet in self._sheets:
+            total += len(self.read_sheet(sheet))
+        return total
+
+    def close(self) -> None:
+        """关闭工作簿"""
+        if self._workbook:
+            self._workbook.close()
+            self._workbook = None
+
+    def __enter__(self) -> 'ExcelReader':
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+
+class TestCase:
+    """测试用例数据类"""
+
+    def __init__(self, data: Dict[str, Any]):
+        self.id = data.get('id', '')
+        self.name = data.get('name', '')
+        self.sheet = data.get('sheet', '')
+        self.row = data.get('row', 0)
+        self.steps: List['TestStep'] = []
+
+        for step_data in data.get('steps', []):
+            self.steps.append(TestStep(step_data))
+
+    def __repr__(self) -> str:
+        return f"TestCase(id={self.id}, name={self.name}, steps={len(self.steps)})"
+
+
+class TestStep:
+    """测试步骤数据类"""
+
+    def __init__(self, data: Dict[str, Any]):
+        self.row = data.get('row', 0)
+        self.description = data.get('description', '')
+        self.keyword = data.get('keyword', '')
+        self.locator = data.get('locator', [])
+        self.value = data.get('value')
+
+    def __repr__(self) -> str:
+        return f"TestStep(keyword={self.keyword}, value={self.value})"

kdtest_pw/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI 模块"""
+
+from .run import main, KDTestRunner
+
+__all__ = ['main', 'KDTestRunner']

kdtest_pw/cli/run.py

@@ -0,0 +1,318 @@
+"""CLI 入口 - 命令行运行测试"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional, List
+
+from ..product import __version__
+from ..core.browser_manager import BrowserManager
+from ..core.config_loader import ConfigLoader
+from ..action.key_retrieval import KeyRetrieval
+from ..cases.case_collector import CaseCollector
+from ..cases.case_executor import CaseExecutor
+from ..cases.read.cell_handler import CellHandler
+from ..plugins.plugin_loader import PluginLoader
+from ..reference import GSTORE, GSDSTORE, INFO
+from ..utils.log.html_report import HtmlReporter
+
+
+class KDTestRunner:
+    """KDTest Playwright 测试运行器"""
+
+    def __init__(self, config_path: Optional[str] = None):
+        """初始化运行器
+
+        Args:
+            config_path: 配置文件路径
+        """
+        self._config_loader: Optional[ConfigLoader] = None
+        self._browser_manager: Optional[BrowserManager] = None
+        self._key_retrieval: Optional[KeyRetrieval] = None
+        self._plugin_loader: Optional[PluginLoader] = None
+        self._case_collector: Optional[CaseCollector] = None
+        self._case_executor: Optional[CaseExecutor] = None
+        self._reporter: Optional[HtmlReporter] = None
+
+        if config_path:
+            self.load_config(config_path)
+
+    def load_config(self, config_path: str) -> None:
+        """加载配置文件
+
+        Args:
+            config_path: 配置文件路径
+        """
+        self._config_loader = ConfigLoader(config_path)
+        INFO(f"配置已加载: {config_path}")
+
+    def setup(self) -> None:
+        """初始化测试环境"""
+        if not self._config_loader:
+            raise RuntimeError("请先加载配置文件")
+
+        config = self._config_loader.config
+
+        # 初始化浏览器管理器
+        self._browser_manager = BrowserManager()
+
+        # 启动浏览器
+        page = self._browser_manager.launch(
+            browser_type=self._config_loader.browser,
+            headless=self._config_loader.headless,
+            slow_mo=self._config_loader.slow_mo,
+            trace=self._config_loader.trace,
+            video=self._config_loader.video,
+            timeout=self._config_loader.timeout,
+        )
+
+        # 初始化关键字分发器
+        self._key_retrieval = KeyRetrieval(page)
+
+        # 初始化插件加载器
+        self._plugin_loader = PluginLoader(page)
+        self._plugin_loader.load_builtin_plugins()
+
+        # 合并插件关键字和元素数据
+        self._key_retrieval.register_plugin_keywords(
+            self._plugin_loader.get_all_keywords()
+        )
+        self._key_retrieval.set_element_data(
+            self._plugin_loader.get_all_element_data()
+        )
+
+        # 初始化单元格处理器
+        cell_handler = CellHandler(
+            self._config_loader.self_defined_parameters
+        )
+
+        # 初始化用例执行器
+        self._case_executor = CaseExecutor(
+            key_retrieval=self._key_retrieval,
+            cell_handler=cell_handler,
+            retry_count=self._config_loader.retry_count if self._config_loader.retry_switch else 0,
+            screenshot_on_fail=True,
+        )
+
+        # 初始化用例收集器
+        self._case_collector = CaseCollector(config)
+
+        # 初始化报告生成器
+        self._reporter = HtmlReporter()
+
+        # 导航到起始 URL
+        if self._config_loader.url:
+            page.goto(self._config_loader.url)
+
+        INFO("测试环境初始化完成")
+
+    def run(
+        self,
+        include_sheets: List[str] = None,
+        exclude_sheets: List[str] = None,
+        case_ids: List[str] = None,
+        case_pattern: str = None,
+    ) -> dict:
+        """运行测试
+
+        Args:
+            include_sheets: 只执行这些 Sheet
+            exclude_sheets: 排除这些 Sheet
+            case_ids: 只执行这些用例 ID
+            case_pattern: 用例名称匹配模式
+
+        Returns:
+            dict: 执行摘要
+        """
+        # 收集用例
+        all_cases = self._case_collector.collect()
+
+        # 过滤用例
+        cases = self._case_collector.filter_cases(
+            include_sheets=include_sheets,
+            exclude_sheets=exclude_sheets,
+            include_ids=case_ids,
+            name_pattern=case_pattern,
+        )
+
+        INFO(f"过滤后用例数: {len(cases)}")
+
+        # 执行用例
+        results = self._case_executor.execute_cases(cases)
+
+        # 生成报告
+        if self._reporter:
+            report_path = self._reporter.generate(results)
+            INFO(f"测试报告: {report_path}")
+
+        return self._case_executor.summary
+
+    def teardown(self, save_trace: str = None) -> None:
+        """清理测试环境
+
+        Args:
+            save_trace: trace 文件保存路径
+        """
+        # 卸载插件
+        if self._plugin_loader:
+            self._plugin_loader.unload_all()
+
+        # 关闭浏览器
+        if self._browser_manager:
+            trace_path = save_trace or (
+                'result/trace/trace.zip' if self._config_loader and self._config_loader.trace else None
+            )
+            self._browser_manager.close(save_trace=trace_path)
+
+        INFO("测试环境已清理")
+
+    def __enter__(self) -> 'KDTestRunner':
+        self.setup()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.teardown()
+
+
+def parse_args() -> argparse.Namespace:
+    """解析命令行参数"""
+    parser = argparse.ArgumentParser(
+        prog='kdtest-pw',
+        description='KDTest Playwright - 关键字驱动测试框架',
+    )
+
+    parser.add_argument(
+        '-v', '--version',
+        action='version',
+        version=f'kdtest-pw {__version__}'
+    )
+
+    parser.add_argument(
+        '-c', '--config',
+        type=str,
+        default='data/parameters.json',
+        help='配置文件路径 (默认: data/parameters.json)'
+    )
+
+    parser.add_argument(
+        '-s', '--sheets',
+        type=str,
+        nargs='+',
+        help='只执行指定的 Sheet'
+    )
+
+    parser.add_argument(
+        '-x', '--exclude',
+        type=str,
+        nargs='+',
+        help='排除指定的 Sheet'
+    )
+
+    parser.add_argument(
+        '-i', '--ids',
+        type=str,
+        nargs='+',
+        help='只执行指定的用例 ID'
+    )
+
+    parser.add_argument(
+        '-p', '--pattern',
+        type=str,
+        help='用例名称匹配模式 (支持通配符)'
+    )
+
+    parser.add_argument(
+        '--browser',
+        type=str,
+        choices=['chromium', 'firefox', 'webkit'],
+        help='覆盖配置中的浏览器类型'
+    )
+
+    parser.add_argument(
+        '--headless',
+        action='store_true',
+        help='无头模式运行'
+    )
+
+    parser.add_argument(
+        '--trace',
+        action='store_true',
+        help='开启 trace 录制'
+    )
+
+    parser.add_argument(
+        '--video',
+        action='store_true',
+        help='开启视频录制'
+    )
+
+    parser.add_argument(
+        '--slow-mo',
+        type=int,
+        help='操作延迟 (毫秒)'
+    )
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    """主入口函数"""
+    args = parse_args()
+
+    # 检查配置文件
+    config_path = Path(args.config)
+    if not config_path.exists():
+        print(f"错误: 配置文件不存在: {config_path}")
+        return 1
+
+    runner = KDTestRunner(str(config_path))
+
+    # 覆盖配置
+    if args.browser:
+        runner._config_loader.set('browser', args.browser)
+    if args.headless:
+        runner._config_loader.set('headless', True)
+    if args.trace:
+        runner._config_loader.set('trace', True)
+    if args.video:
+        runner._config_loader.set('video', True)
+    if args.slow_mo:
+        runner._config_loader.set('slowMo', args.slow_mo)
+
+    try:
+        runner.setup()
+        summary = runner.run(
+            include_sheets=args.sheets,
+            exclude_sheets=args.exclude,
+            case_ids=args.ids,
+            case_pattern=args.pattern,
+        )
+
+        # 输出摘要
+        print("\n" + "=" * 50)
+        print("测试执行摘要")
+        print("=" * 50)
+        print(f"总用例数: {summary['total']}")
+        print(f"通过: {summary['passed']}")
+        print(f"失败: {summary['failed']}")
+        print(f"跳过: {summary['skipped']}")
+        print(f"通过率: {summary['pass_rate']:.1f}%")
+        print(f"执行时间: {summary['duration']:.2f}s")
+        print("=" * 50)
+
+        return 0 if summary['failed'] == 0 else 1
+
+    except KeyboardInterrupt:
+        print("\n测试被中断")
+        return 130
+    except Exception as e:
+        print(f"执行错误: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    finally:
+        runner.teardown()
+
+
+if __name__ == '__main__':
+    sys.exit(main())

kdtest_pw/common.py

@@ -0,0 +1,106 @@
+"""常量和数据存储模块"""
+
+from typing import Dict, Any, List
+from pathlib import Path
+
+# 项目根目录
+PROJECT_ROOT = Path(__file__).parent
+
+# 默认配置
+DEFAULT_CONFIG: Dict[str, Any] = {
+    'browser': 'chromium',
+    'headless': False,
+    'slowMo': 0,
+    'timeout': 30000,
+    'trace': False,
+    'video': False,
+    'retrySwitch': False,
+    'retryCount': 1,
+    'parallel': False,
+}
+
+# 支持的浏览器类型
+BROWSER_TYPES: List[str] = ['chromium', 'firefox', 'webkit']
+
+# 定位器类型映射
+LOCATOR_TYPES: Dict[str, str] = {
+    'id': 'id',
+    'name': 'name',
+    'class': 'class_name',
+    'class_name': 'class_name',
+    'css': 'css',
+    'xpath': 'xpath',
+    'text': 'text',
+    'role': 'role',
+    'data_testid': 'data_testid',
+    'placeholder': 'placeholder',
+    'link_text': 'text',
+    'partial_link_text': 'text',
+}
+
+# 键盘键映射 (Selenium Keys -> Playwright)
+KEY_MAP: Dict[str, str] = {
+    'Keys.ENTER': 'Enter',
+    'Keys.TAB': 'Tab',
+    'Keys.BACK_SPACE': 'Backspace',
+    'Keys.BACKSPACE': 'Backspace',
+    'Keys.ESCAPE': 'Escape',
+    'Keys.DELETE': 'Delete',
+    'Keys.ARROW_UP': 'ArrowUp',
+    'Keys.ARROW_DOWN': 'ArrowDown',
+    'Keys.ARROW_LEFT': 'ArrowLeft',
+    'Keys.ARROW_RIGHT': 'ArrowRight',
+    'Keys.HOME': 'Home',
+    'Keys.END': 'End',
+    'Keys.PAGE_UP': 'PageUp',
+    'Keys.PAGE_DOWN': 'PageDown',
+    'Keys.SPACE': 'Space',
+    'Keys.CONTROL': 'Control',
+    'Keys.ALT': 'Alt',
+    'Keys.SHIFT': 'Shift',
+    'Keys.F1': 'F1',
+    'Keys.F2': 'F2',
+    'Keys.F3': 'F3',
+    'Keys.F4': 'F4',
+    'Keys.F5': 'F5',
+    'Keys.F6': 'F6',
+    'Keys.F7': 'F7',
+    'Keys.F8': 'F8',
+    'Keys.F9': 'F9',
+    'Keys.F10': 'F10',
+    'Keys.F11': 'F11',
+    'Keys.F12': 'F12',
+    # 组合键
+    'Keys.CONTROL+a': 'Control+a',
+    'Keys.CONTROL+c': 'Control+c',
+    'Keys.CONTROL+v': 'Control+v',
+    'Keys.CONTROL+x': 'Control+x',
+    'Keys.CONTROL+z': 'Control+z',
+    'Keys.CONTROL+s': 'Control+s',
+}
+
+# 断言模式
+ASSERT_MODES: List[str] = ['equals', 'contains', 'regex', 'gt', 'lt', 'gte', 'lte']
+
+# 元素等待状态
+WAIT_STATES: List[str] = ['visible', 'hidden', 'attached', 'detached']
+
+# 结果目录
+RESULT_DIRS: Dict[str, str] = {
+    'report': 'result/report',
+    'log': 'result/log',
+    'trace': 'result/trace',
+    'video': 'result/video',
+    'screenshot': 'result/screenshot',
+}
+
+# Excel列映射
+EXCEL_COLUMNS: Dict[str, int] = {
+    'case_id': 0,       # A列 - 用例ID
+    'case_name': 1,     # B列 - 用例名称
+    'description': 2,   # C列 - 步骤描述
+    'keyword': 3,       # D列 - 关键字
+    'locator_start': 4, # E列开始 - 定位信息
+    'locator_end': 13,  # N列结束 - 定位信息
+    'value': 14,        # O列 - 操作值
+}

kdtest_pw/core/__init__.py

@@ -0,0 +1,7 @@
+"""核心模块"""
+
+from .browser_manager import BrowserManager
+from .config_loader import ConfigLoader
+from .page_context import PageContext
+
+__all__ = ['BrowserManager', 'ConfigLoader', 'PageContext']