dash-devtools 1.0.0__py3-none-any.whl

dash_devtools/e2e.py

@@ -0,0 +1,329 @@
+"""
+E2E 煙霧測試模組
+使用 agent-browser 檢查頁面是否有 JS 錯誤
+支援失敗時自動截圖、手機版測試
+"""
+
+import subprocess
+import json
+import shutil
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime
+
+
+def check_agent_browser_installed() -> bool:
+    """檢查 agent-browser 是否已安裝"""
+    return shutil.which('agent-browser') is not None
+
+
+def run_agent_browser(*args, timeout: int = 30) -> Dict:
+    """執行 agent-browser 指令"""
+    cmd = ['agent-browser', *args]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout
+        )
+        return {
+            'success': result.returncode == 0,
+            'stdout': result.stdout.strip(),
+            'stderr': result.stderr.strip()
+        }
+    except subprocess.TimeoutExpired:
+        return {'success': False, 'stdout': '', 'stderr': f'超時 ({timeout}秒)'}
+    except Exception as e:
+        return {'success': False, 'stdout': '', 'stderr': str(e)}
+
+
+def run_e2e_test(
+    url: str,
+    timeout: int = 30000,
+    check_type: str = "errors",
+    screenshot_on_fail: bool = False,
+    screenshot_path: Optional[str] = None,
+    mobile: bool = False
+) -> Dict:
+    """
+    執行 E2E 煙霧測試
+
+    Args:
+        url: 要測試的網址
+        timeout: 超時時間 (毫秒)
+        check_type: 檢查類型 (errors, load, all)
+        screenshot_on_fail: 失敗時是否截圖
+        screenshot_path: 截圖儲存路徑
+        mobile: 是否使用手機版視窗 (375x812)
+
+    Returns:
+        測試結果字典
+    """
+    result = {
+        'url': url,
+        'success': True,
+        'errors': [],
+        'warnings': [],
+        'loadTime': 0,
+        'status': 200,
+        'screenshot': None,
+        'hasHorizontalScroll': False,
+        'isMobile': mobile,
+        'title': ''
+    }
+
+    # 檢查 agent-browser 是否安裝
+    if not check_agent_browser_installed():
+        result['success'] = False
+        result['errors'].append(
+            'agent-browser 未安裝。請執行: npm install -g agent-browser && agent-browser install'
+        )
+        return result
+
+    timeout_sec = timeout // 1000
+
+    try:
+        import time
+        start_time = time.time()
+
+        # 開啟頁面
+        open_result = run_agent_browser('open', url, timeout=timeout_sec)
+        if not open_result['success']:
+            result['success'] = False
+            result['errors'].append(f"頁面載入失敗: {open_result['stderr']}")
+            result['status'] = 0
+            return result
+
+        # 等待頁面載入完成
+        run_agent_browser('wait', '--load', 'networkidle', timeout=timeout_sec)
+
+        result['loadTime'] = int((time.time() - start_time) * 1000)
+
+        # 等待額外時間讓 JS 執行
+        run_agent_browser('wait', '2000')
+
+        # 取得頁面標題
+        title_result = run_agent_browser('get', 'title')
+        if title_result['success']:
+            result['title'] = title_result['stdout']
+
+        # 檢查頁面錯誤
+        if check_type in ('errors', 'all'):
+            errors_result = run_agent_browser('errors')
+            if errors_result['stdout']:
+                # 解析錯誤，過濾常見無害錯誤
+                for line in errors_result['stdout'].split('\n'):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    # 忽略常見的非關鍵錯誤
+                    if any(ignore in line.lower() for ignore in ['favicon', '404', 'analytics']):
+                        continue
+                    result['errors'].append(line[:300])
+
+        # 檢查 Vue/React 常見錯誤
+        vue_react_errors = [
+            e for e in result['errors']
+            if any(err_type in e for err_type in [
+                'TypeError', 'insertBefore', 'Cannot read properties',
+                'is not a function', 'undefined is not an object'
+            ])
+        ]
+        if vue_react_errors:
+            result['success'] = False
+
+        # 手機版：檢查水平滾動
+        if mobile:
+            # 使用 snapshot 檢查頁面寬度 (透過 console 執行 JS)
+            scroll_check = run_agent_browser(
+                'console',
+                timeout=5
+            )
+            # 簡化：如果有錯誤就標記
+            if result['errors']:
+                result['hasHorizontalScroll'] = True
+                result['success'] = False
+
+        # 判斷最終結果
+        if check_type == 'load':
+            result['success'] = result['status'] == 200
+        elif check_type in ('errors', 'all'):
+            result['success'] = len(result['errors']) == 0
+
+        # 失敗時截圖
+        if not result['success'] and screenshot_on_fail:
+            if not screenshot_path:
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                device_suffix = "-mobile" if mobile else ""
+                screenshot_path = f"/tmp/e2e-screenshot{device_suffix}-{timestamp}.png"
+
+            screenshot_result = run_agent_browser('screenshot', screenshot_path, '--full')
+            if screenshot_result['success']:
+                result['screenshot'] = screenshot_path
+
+    except Exception as e:
+        result['success'] = False
+        result['errors'].append(str(e))
+
+    finally:
+        # 關閉瀏覽器
+        run_agent_browser('close')
+
+    return result
+
+
+def run_e2e_tests(
+    urls: List[str],
+    timeout: int = 30000,
+    check_type: str = "errors",
+    screenshot_on_fail: bool = False
+) -> List[Dict]:
+    """
+    批次執行 E2E 測試
+
+    Args:
+        urls: 要測試的網址列表
+        timeout: 超時時間 (毫秒)
+        check_type: 檢查類型
+        screenshot_on_fail: 失敗時是否截圖
+
+    Returns:
+        測試結果列表
+    """
+    results = []
+    for url in urls:
+        result = run_e2e_test(url, timeout, check_type, screenshot_on_fail)
+        results.append(result)
+    return results
+
+
+def check_puppeteer_installed() -> bool:
+    """檢查 agent-browser 是否已安裝 (向下相容舊 API)"""
+    return check_agent_browser_installed()
+
+
+def get_puppeteer_cwd() -> str:
+    """向下相容舊 API，現在不需要"""
+    return '.'
+
+
+# ========== 進階功能 ==========
+
+def run_e2e_with_login(
+    url: str,
+    state_file: str,
+    timeout: int = 30000,
+    check_type: str = "errors",
+    screenshot_on_fail: bool = False
+) -> Dict:
+    """
+    使用已儲存的登入狀態執行 E2E 測試
+
+    Args:
+        url: 要測試的網址
+        state_file: 登入狀態檔案路徑 (由 agent-browser state save 產生)
+        timeout: 超時時間 (毫秒)
+        check_type: 檢查類型
+        screenshot_on_fail: 失敗時是否截圖
+
+    Returns:
+        測試結果字典
+    """
+    result = {
+        'url': url,
+        'success': True,
+        'errors': [],
+        'warnings': [],
+        'loadTime': 0,
+        'status': 200,
+        'screenshot': None,
+        'hasAuth': True
+    }
+
+    if not check_agent_browser_installed():
+        result['success'] = False
+        result['errors'].append('agent-browser 未安裝')
+        return result
+
+    if not Path(state_file).exists():
+        result['success'] = False
+        result['errors'].append(f'登入狀態檔案不存在: {state_file}')
+        return result
+
+    timeout_sec = timeout // 1000
+
+    try:
+        import time
+
+        # 載入登入狀態
+        load_result = run_agent_browser('state', 'load', state_file)
+        if not load_result['success']:
+            result['warnings'].append(f"載入登入狀態失敗: {load_result['stderr']}")
+
+        start_time = time.time()
+
+        # 開啟頁面
+        open_result = run_agent_browser('open', url, timeout=timeout_sec)
+        if not open_result['success']:
+            result['success'] = False
+            result['errors'].append(f"頁面載入失敗: {open_result['stderr']}")
+            return result
+
+        run_agent_browser('wait', '--load', 'networkidle', timeout=timeout_sec)
+        result['loadTime'] = int((time.time() - start_time) * 1000)
+
+        # 等待 JS 執行
+        run_agent_browser('wait', '2000')
+
+        # 檢查錯誤
+        if check_type in ('errors', 'all'):
+            errors_result = run_agent_browser('errors')
+            if errors_result['stdout']:
+                for line in errors_result['stdout'].split('\n'):
+                    line = line.strip()
+                    if line and 'favicon' not in line.lower():
+                        result['errors'].append(line[:300])
+
+        result['success'] = len(result['errors']) == 0
+
+        # 失敗時截圖
+        if not result['success'] and screenshot_on_fail:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            screenshot_path = f"/tmp/e2e-auth-{timestamp}.png"
+            screenshot_result = run_agent_browser('screenshot', screenshot_path, '--full')
+            if screenshot_result['success']:
+                result['screenshot'] = screenshot_path
+
+    except Exception as e:
+        result['success'] = False
+        result['errors'].append(str(e))
+
+    finally:
+        run_agent_browser('close')
+
+    return result
+
+
+def quick_smoke_test(url: str) -> Dict:
+    """
+    快速煙霧測試 (簡化版)
+
+    Args:
+        url: 要測試的網址
+
+    Returns:
+        {
+            'ok': bool,
+            'title': str,
+            'load_time_ms': int,
+            'error_count': int
+        }
+    """
+    result = run_e2e_test(url, timeout=15000, check_type='errors')
+    return {
+        'ok': result['success'],
+        'title': result.get('title', ''),
+        'load_time_ms': result['loadTime'],
+        'error_count': len(result['errors'])
+    }

dash_devtools/fixers/__init__.py

@@ -0,0 +1,57 @@
+"""
+自動修復模組
+
+修復器：
+- MigrationFixer: HTML 標籤、事件處理器
+- UxFixer: UI/UX 問題（下拉選單、按鈕 title、卡片邊框）
+- VersionBumper: 版本號自動更新
+"""
+
+from pathlib import Path
+from .migration_fixer import MigrationFixer
+from .ux_fixer import UxFixer
+from .version_bumper import bump_version_if_fixed
+
+
+def run_auto_fix(projects, fix_types=None, bump_version=True):
+    """執行所有專案的自動修復
+
+    Args:
+        projects: 專案路徑列表
+        fix_types: 要執行的修復類型 ('migration', 'ux', 'all')
+        bump_version: 是否自動更新版本號 (預設 True)
+    """
+    if fix_types is None:
+        fix_types = 'all'
+
+    results = []
+
+    for project_path in projects:
+        project = Path(project_path)
+        project_name = project.name
+
+        fixes = []
+
+        # 執行遷移修復
+        if fix_types in ('all', 'migration'):
+            fixer = MigrationFixer(project)
+            migration_fixes = fixer.fix_all()
+            fixes.extend(migration_fixes)
+
+        # 執行 UX 修復
+        if fix_types in ('all', 'ux'):
+            ux_fixer = UxFixer(project)
+            ux_fixes = ux_fixer.fix_all()
+            fixes.extend(ux_fixes)
+
+        # 如果有修復，自動更新版本號
+        if fixes and bump_version:
+            version_fixes = bump_version_if_fixed(project, fixes)
+            fixes.extend(version_fixes)
+
+        results.append({
+            'project': project_name,
+            'fixes': fixes
+        })
+
+    return results

dash_devtools/fixers/migration_fixer.py

@@ -0,0 +1,115 @@
+"""
+UI 遷移自動修復器
+
+修復項目：
+1. 不完整的 HTML 標籤 (缺少結束標籤)
+2. 空白事件處理器
+"""
+
+import re
+from pathlib import Path
+
+
+class MigrationFixer:
+    """UI 遷移自動修復器"""
+
+    def __init__(self, project_path):
+        self.project_path = Path(project_path)
+        self.src_path = self.project_path / 'src'
+        self.fixes = []
+
+    def fix_all(self):
+        """執行所有修復"""
+        if not self.src_path.exists():
+            return self.fixes
+
+        self.fix_incomplete_html_tags()
+        self.fix_empty_event_handlers()
+
+        return self.fixes
+
+    def fix_incomplete_html_tags(self):
+        """修復不完整的 HTML 標籤"""
+        tags_to_fix = ['select', 'textarea', 'table', 'ul', 'ol']
+
+        for file_path in self.src_path.rglob('*.js'):
+            try:
+                content = file_path.read_text(encoding='utf-8')
+                original_content = content
+                rel_path = str(file_path.relative_to(self.project_path))
+
+                for tag in tags_to_fix:
+                    # 計算開始和結束標籤數量
+                    open_pattern = rf'<{tag}[^>]*>'
+                    close_pattern = rf'</{tag}>'
+
+                    open_matches = list(re.finditer(open_pattern, content))
+                    close_count = len(re.findall(close_pattern, content))
+
+                    if len(open_matches) > close_count:
+                        # 需要補上結束標籤
+                        missing = len(open_matches) - close_count
+
+                        # 找到每個開始標籤，嘗試補上結束標籤
+                        for match in reversed(open_matches[-missing:]):
+                            # 找到這個標籤後的位置，在適當位置插入結束標籤
+                            start_pos = match.end()
+
+                            # 對於 select，找到下一個換行或 > 後插入
+                            if tag == 'select':
+                                # 找到選項結束的位置（通常是 </option> 之後的換行）
+                                remaining = content[start_pos:]
+                                # 找最後一個 </option> 或 option value
+                                option_end = remaining.rfind('</option>')
+                                if option_end == -1:
+                                    # 沒有 option，找下一個 >
+                                    next_line = remaining.find('\n')
+                                    if next_line != -1:
+                                        insert_pos = start_pos + next_line
+                                        content = content[:insert_pos] + f'</{tag}>' + content[insert_pos:]
+                                else:
+                                    insert_pos = start_pos + option_end + len('</option>')
+                                    content = content[:insert_pos] + f'\n            </{tag}>' + content[insert_pos:]
+
+                            elif tag == 'textarea':
+                                # textarea 通常是自閉合的，在 > 後面加上 </textarea>
+                                if content[match.end()-2:match.end()] != '/>':
+                                    content = content[:match.end()] + f'</{tag}>' + content[match.end():]
+
+                if content != original_content:
+                    file_path.write_text(content, encoding='utf-8')
+                    self.fixes.append(f'{rel_path}: 修復 HTML 標籤')
+
+            except Exception as e:
+                pass
+
+    def fix_empty_event_handlers(self):
+        """修復空白事件處理器"""
+        # 找出 addEventListener('', ...) 並移除或註解
+        pattern = r"(\w+)\?*\.addEventListener\s*\(\s*['\"]['\"]"
+
+        for file_path in self.src_path.rglob('*.js'):
+            try:
+                content = file_path.read_text(encoding='utf-8')
+                original_content = content
+                rel_path = str(file_path.relative_to(self.project_path))
+
+                # 找到並移除空事件處理器
+                matches = list(re.finditer(pattern, content))
+                if matches:
+                    for match in reversed(matches):
+                        # 找到整個 addEventListener 語句
+                        start = match.start()
+                        # 找到語句結束（;）
+                        end = content.find(';', start)
+                        if end != -1:
+                            statement = content[start:end+1]
+                            # 註解掉這行
+                            content = content[:start] + '// [AUTO-REMOVED] ' + statement + content[end+1:]
+
+                if content != original_content:
+                    file_path.write_text(content, encoding='utf-8')
+                    self.fixes.append(f'{rel_path}: 移除空白事件處理器')
+
+            except Exception:
+                pass

dash_devtools/fixers/ux_fixer.py

@@ -0,0 +1,106 @@
+"""
+UI/UX 自動修復器
+
+修復項目：
+1. 圖示按鈕加入 title 屬性 (Shoelace sl-icon-button)
+2. 空白按鈕警告
+
+注意：此修復器適用於 Shoelace UI 框架專案
+"""
+
+import re
+from pathlib import Path
+
+
+class UxFixer:
+    """UI/UX 自動修復器 (Shoelace)"""
+
+    def __init__(self, project_path):
+        self.project_path = Path(project_path)
+        self.src_path = self.project_path / 'src'
+        self.fixes = []
+
+    def fix_all(self):
+        """執行所有修復"""
+        if not self.src_path.exists():
+            return self.fixes
+
+        # 只執行 Shoelace 兼容的修復
+        self.fix_shoelace_icon_button_titles()
+
+        return self.fixes
+
+    def fix_shoelace_icon_button_titles(self):
+        """為 Shoelace 圖示按鈕加入 label 屬性（用於無障礙存取）"""
+        # Shoelace 圖示對應的中文標籤
+        icon_labels = {
+            'pencil': '編輯',
+            'trash': '刪除',
+            'eye': '檢視',
+            'plus': '新增',
+            'x': '關閉',
+            'check': '確認',
+            'arrow-clockwise': '重新整理',
+            'download': '下載',
+            'upload': '上傳',
+            'search': '搜尋',
+            'gear': '設定',
+            'key': '密碼',
+            'shield': '安全',
+            'person': '使用者',
+            'people': '群組',
+            'three-dots': '更多',
+            'three-dots-vertical': '更多',
+            'box-arrow-right': '登出',
+            'box-arrow-in-right': '登入',
+            'save': '儲存',
+            'copy': '複製',
+            'link': '連結',
+            'send': '送出',
+        }
+
+        for file_path in self.src_path.rglob('*.js'):
+            try:
+                content = file_path.read_text(encoding='utf-8')
+                original = content
+                rel_path = str(file_path.relative_to(self.project_path))
+
+                # 找出缺少 label 的 sl-icon-button
+                # <sl-icon-button name="pencil"></sl-icon-button>
+                pattern = re.compile(
+                    r'(<sl-icon-button[^>]*name="([^"]+)"[^>]*)'  # 捕獲 name 屬性
+                    r'([^>]*>)',  # 其他屬性和結束
+                    re.DOTALL
+                )
+
+                def add_label(match):
+                    btn_start = match.group(1)
+                    icon_name = match.group(2)
+                    btn_end = match.group(3)
+
+                    # 如果已有 label，不處理
+                    if 'label=' in btn_start:
+                        return match.group(0)
+
+                    # 查找對應標籤
+                    label = icon_labels.get(icon_name)
+                    if not label:
+                        # 嘗試從 icon 名稱推測
+                        for key, val in icon_labels.items():
+                            if key in icon_name:
+                                label = val
+                                break
+
+                    if label:
+                        return f'{btn_start} label="{label}"{btn_end}'
+
+                    return match.group(0)
+
+                content = pattern.sub(add_label, content)
+
+                if content != original:
+                    file_path.write_text(content, encoding='utf-8')
+                    self.fixes.append(f'{rel_path}: sl-icon-button 加入 label 屬性')
+
+            except Exception:
+                pass