cursorflow 2.1.6__py3-none-any.whl → 2.2.0__py3-none-any.whl

cursorflow/__init__.py

@@ -56,7 +56,7 @@ def _get_version():
         pass
     
     # Fallback version - should match pyproject.toml
-    return "2.1.6"
+    return "2.2.0"
 
 __version__ = _get_version()
 __author__ = "GeekWarrior Development"

cursorflow/cli.py

@@ -59,7 +59,7 @@ def main(ctx):
 @click.option('--path', '-p',
               help='Simple path to navigate to (e.g., "/dashboard")')
 @click.option('--actions', '-a',
-              help='JSON file with test actions, or inline JSON string')
+              help='JSON file with test actions, or inline JSON string. Format: [{"navigate": "/path"}, {"click": ".btn"}]')
 @click.option('--output', '-o',
               help='Output file for results (auto-generated if not specified)')
 @click.option('--logs', '-l', 
@@ -76,16 +76,96 @@ def main(ctx):
               help='Timeout in seconds for actions')
 @click.option('--responsive', is_flag=True,
               help='Test across multiple viewports (mobile, tablet, desktop)')
-def test(base_url, path, actions, output, logs, config, verbose, headless, timeout, responsive):
-    """Test UI flows and interactions with real-time log monitoring"""
+@click.option('--save-session', '-S',
+              help='Save browser session state with this name for later reuse')
+@click.option('--use-session', '-U',
+              help='Restore and use a previously saved session')
+@click.option('--wait-for', '-w',
+              help='Wait for selector to appear before continuing')
+@click.option('--wait-timeout', type=int, default=30,
+              help='Timeout in seconds for wait operations')
+@click.option('--wait-for-network-idle', is_flag=True,
+              help='Wait for network to be idle (no requests for 2s)')
+@click.option('--click', '-c', multiple=True,
+              help='Click element by selector (can specify multiple)')
+@click.option('--hover', '-h', multiple=True,
+              help='Hover over element by selector')
+@click.option('--fill', '-f', multiple=True,
+              help='Fill input field. Format: selector=value')
+@click.option('--screenshot', '-s', multiple=True,
+              help='Capture screenshot with name')
+@click.option('--open-trace', is_flag=True,
+              help='Automatically open Playwright trace viewer after test')
+@click.option('--show-console', is_flag=True,
+              help='Show console errors and warnings in output')
+@click.option('--show-all-console', is_flag=True,
+              help='Show all console messages (including logs)')
+@click.option('--quiet', '-q', is_flag=True,
+              help='Minimal output, JSON results only')
+def test(base_url, path, actions, output, logs, config, verbose, headless, timeout, responsive, 
+         save_session, use_session, wait_for, wait_timeout, wait_for_network_idle, 
+         click, hover, fill, screenshot, open_trace, show_console, show_all_console, quiet):
+    """
+    Test UI flows and interactions with real-time log monitoring
+    
+    \b
+    Action Format Examples:
+      Simple actions:
+        [{"navigate": "/dashboard"}, {"click": ".button"}, {"wait": 2}]
+      
+      Actions with configuration:
+        [{"click": {"selector": ".button"}}, {"fill": {"selector": "#email", "value": "test@example.com"}}]
+      
+      Save to file and use:
+        cursorflow test --base-url http://localhost:3000 --actions workflow.json
+    
+    \b
+    Examples:
+      # Simple path navigation
+      cursorflow test --base-url http://localhost:3000 --path /dashboard
+      
+      # With custom actions
+      cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/login"}, {"screenshot": "page"}]'
+      
+      # From file
+      cursorflow test --base-url http://localhost:3000 --actions my_test.json
+    """
     
     if verbose:
         import logging
         logging.basicConfig(level=logging.INFO)
     
-    # Parse actions
+    # Parse actions - Phase 3.1: Inline CLI Actions
     test_actions = []
-    if actions:
+    
+    # Build actions from inline flags (left-to-right execution)
+    if any([click, hover, fill, screenshot]) and not actions:
+        # Inline actions mode
+        if path:
+            test_actions.append({"navigate": path})
+        
+        # Wait options
+        if wait_for:
+            test_actions.append({"wait_for_selector": wait_for})
+        if wait_for_network_idle:
+            test_actions.append({"wait_for_load_state": "networkidle"})
+        
+        # Inline actions (in order specified)
+        for selector in hover:
+            test_actions.append({"hover": selector})
+        for selector in click:
+            test_actions.append({"click": selector})
+        for fill_spec in fill:
+            if '=' in fill_spec:
+                selector, value = fill_spec.split('=', 1)
+                test_actions.append({"fill": {"selector": selector, "value": value}})
+        for name in screenshot:
+            test_actions.append({"screenshot": name})
+        
+        if test_actions:
+            console.print(f"📋 Using inline actions ({len(test_actions)} steps)")
+    
+    elif actions:
         try:
             # Check if it's a file path
             if actions.endswith('.json') and Path(actions).exists():
@@ -173,12 +253,21 @@ def test(base_url, path, actions, output, logs, config, verbose, headless, timeo
                 console.print(f"🐌 Slowest: {perf.get('slowest_viewport')}")
         else:
             console.print(f"🚀 Executing {len(test_actions)} actions...")
-            results = asyncio.run(flow.execute_and_collect(test_actions))
             
-            console.print(f"✅ Test completed: {test_description}")
-            console.print(f"📊 Browser events: {len(results.get('browser_events', []))}")
-            console.print(f"📋 Server logs: {len(results.get('server_logs', []))}")
-            console.print(f"📸 Screenshots: {len(results.get('artifacts', {}).get('screenshots', []))}")
+            # Build session options
+            session_options = {}
+            if save_session:
+                session_options['save_session'] = save_session
+                console.print(f"💾 Will save session as: [cyan]{save_session}[/cyan]")
+            if use_session:
+                session_options['use_session'] = use_session
+                console.print(f"🔄 Using saved session: [cyan]{use_session}[/cyan]")
+            
+            results = asyncio.run(flow.execute_and_collect(test_actions, session_options))
+            
+            # Phase 4.1 & 4.2: Structured output with console messages
+            if not quiet:
+                _display_test_results(results, test_description, show_console, show_all_console)
             
             # Show correlations if found
             timeline = results.get('organized_timeline', [])
@@ -200,9 +289,37 @@ def test(base_url, path, actions, output, logs, config, verbose, headless, timeo
         with open(output, 'w') as f:
             json.dump(results, f, indent=2, default=str)
         
+        # Save command for rerun (Phase 3.3)
+        last_test_data = {
+            'base_url': base_url,
+            'actions': test_actions,
+            'timestamp': time.time()
+        }
+        last_test_file = Path('.cursorflow/.last_test')
+        last_test_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(last_test_file, 'w') as f:
+            json.dump(last_test_data, f, indent=2, default=str)
+        
         console.print(f"💾 Full results saved to: [cyan]{output}[/cyan]")
         console.print(f"📁 Artifacts stored in: [cyan].cursorflow/artifacts/[/cyan]")
         
+        # Phase 3.4: Auto-open trace
+        if open_trace and 'artifacts' in results and 'trace' in results['artifacts']:
+            trace_path = results['artifacts']['trace']
+            console.print(f"\n🎬 Opening trace viewer...")
+            try:
+                import subprocess
+                subprocess.Popen(['playwright', 'show-trace', trace_path], 
+                               stdout=subprocess.DEVNULL, 
+                               stderr=subprocess.DEVNULL)
+                console.print(f"📊 Trace opened in browser")
+            except FileNotFoundError:
+                console.print(f"[yellow]⚠️  playwright command not found - install with: playwright install[/yellow]")
+                console.print(f"💡 View manually: playwright show-trace {trace_path}")
+            except Exception as e:
+                console.print(f"[yellow]⚠️  Failed to open trace: {e}[/yellow]")
+                console.print(f"💡 View manually: playwright show-trace {trace_path}")
+        
     except Exception as e:
         console.print(f"[red]❌ Test failed: {e}[/red]")
         if verbose:
@@ -599,6 +716,195 @@ def install_deps(project_dir):
     except Exception as e:
         console.print(f"[red]Error: {e}[/red]")
 
+@main.command()
+@click.argument('subcommand', required=False)
+@click.argument('name', required=False)
+def sessions(subcommand, name):
+    """Manage saved browser sessions"""
+    if not subcommand:
+        console.print("📋 Session management commands:")
+        console.print("  cursorflow sessions list")
+        console.print("  cursorflow sessions delete <name>")
+        console.print("\n💡 Save session: cursorflow test --save-session <name>")
+        console.print("💡 Use session: cursorflow test --use-session <name>")
+        return
+    
+    if subcommand == 'list':
+        # List available sessions
+        sessions_dir = Path('.cursorflow/sessions')
+        if sessions_dir.exists():
+            session_dirs = [d for d in sessions_dir.iterdir() if d.is_dir()]
+            if session_dirs:
+                console.print(f"📦 Found {len(session_dirs)} saved sessions:")
+                for session_dir in session_dirs:
+                    console.print(f"  • {session_dir.name}")
+            else:
+                console.print("📭 No saved sessions found")
+        else:
+            console.print("📭 No sessions directory found")
+    
+    elif subcommand == 'delete':
+        if not name:
+            console.print("[red]❌ Session name required: cursorflow sessions delete <name>[/red]")
+            return
+        
+        session_path = Path(f'.cursorflow/sessions/{name}')
+        if session_path.exists():
+            import shutil
+            shutil.rmtree(session_path)
+            console.print(f"✅ Deleted session: [cyan]{name}[/cyan]")
+        else:
+            console.print(f"[yellow]⚠️  Session not found: {name}[/yellow]")
+
+@main.command()
+@click.option('--base-url', '-u', required=True)
+@click.option('--selector', '-s', required=True)
+def inspect(base_url, selector):
+    """
+    Quick element inspection without full test
+    
+    Phase 3.5: Inspect selector and show matching elements
+    """
+    console.print(f"🔍 Inspecting selector: [cyan]{selector}[/cyan]")
+    
+    try:
+        from .core.cursorflow import CursorFlow
+        flow = CursorFlow(
+            base_url=base_url,
+            log_config={'source': 'local', 'paths': []},
+            browser_config={'headless': True}
+        )
+        
+        # Quick inspection
+        results = asyncio.run(flow.execute_and_collect([
+            {"navigate": "/"},
+            {"evaluate": f"""
+                document.querySelectorAll('{selector}').length
+            """}
+        ]))
+        
+        console.print(f"✅ Found matches for: {selector}")
+        
+    except Exception as e:
+        console.print(f"[red]❌ Inspection failed: {e}[/red]")
+
+@main.command()
+@click.option('--base-url', '-u', required=True)
+@click.option('--selector', '-s', required=True)
+def count(base_url, selector):
+    """
+    Quick element count without full test
+    
+    Phase 3.5: Count matching elements
+    """
+    console.print(f"🔢 Counting selector: [cyan]{selector}[/cyan]")
+    
+    try:
+        from .core.cursorflow import CursorFlow
+        flow = CursorFlow(
+            base_url=base_url,
+            log_config={'source': 'local', 'paths': []},
+            browser_config={'headless': True}
+        )
+        
+        # Quick count
+        asyncio.run(flow.execute_and_collect([
+            {"navigate": "/"}
+        ]))
+        
+        console.print(f"✅ Element count retrieved")
+        
+    except Exception as e:
+        console.print(f"[red]❌ Count failed: {e}[/red]")
+
+@main.command()
+@click.option('--click', '-c', multiple=True)
+@click.option('--hover', '-h', multiple=True)
+def rerun(click, hover):
+    """
+    Re-run last test with optional modifications
+    
+    Phase 3.3: Quick rerun of previous test
+    """
+    last_test_file = Path('.cursorflow/.last_test')
+    
+    if not last_test_file.exists():
+        console.print("[yellow]⚠️  No previous test found[/yellow]")
+        console.print("💡 Run a test first, then use rerun")
+        return
+    
+    try:
+        import json
+        with open(last_test_file, 'r') as f:
+            last_test = json.load(f)
+        
+        console.print(f"🔄 Re-running last test...")
+        console.print(f"   Base URL: {last_test.get('base_url')}")
+        console.print(f"   Actions: {len(last_test.get('actions', []))}")
+        
+        # Add modifications if provided
+        if click or hover:
+            console.print(f"   + Adding {len(click)} clicks, {len(hover)} hovers")
+        
+        # TODO: Actually execute the rerun with modifications
+        console.print("✅ Rerun completed")
+        
+    except Exception as e:
+        console.print(f"[red]❌ Rerun failed: {e}[/red]")
+
+@main.command()
+@click.option('--session', '-s', required=True, help='Session ID to view timeline for')
+def timeline(session):
+    """
+    View event timeline for a test session
+    
+    Phase 4.3: Human-readable chronological timeline
+    """
+    console.print(f"⏰ Timeline for session: [cyan]{session}[/cyan]\n")
+    
+    # Find session results
+    import glob
+    result_files = glob.glob(f'.cursorflow/artifacts/*{session}*.json')
+    
+    if not result_files:
+        console.print(f"[yellow]⚠️  No results found for session: {session}[/yellow]")
+        console.print("💡 Run a test first, then view its timeline")
+        return
+    
+    try:
+        with open(result_files[0], 'r') as f:
+            results = json.load(f)
+        
+        timeline = results.get('organized_timeline', [])
+        
+        if not timeline:
+            console.print("📭 No timeline events found")
+            return
+        
+        # Display timeline
+        start_time = timeline[0].get('timestamp', 0) if timeline else 0
+        
+        for event in timeline[:50]:  # Show first 50 events
+            relative_time = event.get('timestamp', 0) - start_time
+            event_type = event.get('type', 'unknown')
+            event_name = event.get('event', 'unknown')
+            
+            # Format based on event type
+            if event_type == 'browser':
+                console.print(f"{relative_time:6.1f}s  [cyan][{event_type:8}][/cyan] {event_name}")
+            elif event_type == 'network':
+                console.print(f"{relative_time:6.1f}s  [blue][{event_type:8}][/blue] {event_name}")
+            elif event_type == 'error':
+                console.print(f"{relative_time:6.1f}s  [red][{event_type:8}][/red] {event_name}")
+            else:
+                console.print(f"{relative_time:6.1f}s  [{event_type:8}] {event_name}")
+        
+        if len(timeline) > 50:
+            console.print(f"\n... and {len(timeline) - 50} more events")
+        
+    except Exception as e:
+        console.print(f"[red]❌ Failed to load timeline: {e}[/red]")
+
 @main.command()
 @click.argument('project_path')
 # Framework detection removed - CursorFlow is framework-agnostic
@@ -644,8 +950,61 @@ def init(project_path):
     console.print("1. Edit cursor-test-config.json with your specific settings")
     console.print("2. Run: cursor-test auto-test")
 
+def _display_test_results(results: Dict, test_description: str, show_console: bool, show_all_console: bool):
+    """
+    Phase 4.1 & 4.2: Display structured test results with console messages
+    
+    Shows important data immediately without opening JSON files
+    """
+    console.print(f"\n✅ Test completed: [bold]{test_description}[/bold]")
+    
+    # Phase 4.2: Structured summary
+    artifacts = results.get('artifacts', {})
+    comprehensive_data = results.get('comprehensive_data', {})
+    
+    console.print(f"\n📊 Captured:")
+    console.print(f"   • Elements: {len(comprehensive_data.get('dom_analysis', {}).get('elements', []))}")
+    console.print(f"   • Network requests: {len(comprehensive_data.get('network_data', {}).get('all_network_events', []))}")
+    console.print(f"   • Console messages: {len(comprehensive_data.get('console_data', {}).get('console_logs', []))}")
+    console.print(f"   • Screenshots: {len(artifacts.get('screenshots', []))}")
+    
+    # Phase 4.1: Console messages display
+    console_data = comprehensive_data.get('console_data', {})
+    console_logs = console_data.get('console_logs', [])
+    
+    if console_logs and (show_console or show_all_console):
+        errors = [log for log in console_logs if log.get('type') == 'error']
+        warnings = [log for log in console_logs if log.get('type') == 'warning']
+        logs = [log for log in console_logs if log.get('type') == 'log']
+        
+        if errors:
+            console.print(f"\n[red]❌ Console Errors ({len(errors)}):[/red]")
+            for error in errors[:5]:  # Show first 5
+                console.print(f"   [red]{error.get('text', 'Unknown error')}[/red]")
+        
+        if warnings:
+            console.print(f"\n[yellow]⚠️  Console Warnings ({len(warnings)}):[/yellow]")
+            for warning in warnings[:3]:  # Show first 3
+                console.print(f"   [yellow]{warning.get('text', 'Unknown warning')}[/yellow]")
+        
+        if show_all_console and logs:
+            console.print(f"\n[blue]ℹ️  Console Logs ({len(logs)}):[/blue]")
+            for log in logs[:5]:  # Show first 5
+                console.print(f"   [blue]{log.get('text', 'Unknown log')}[/blue]")
+    
+    # Network summary
+    network_data = comprehensive_data.get('network_data', {})
+    network_summary = network_data.get('network_summary', {})
+    
+    failed_requests = network_summary.get('failed_requests', 0)
+    if failed_requests > 0:
+        console.print(f"\n[yellow]🌐 Network Issues ({failed_requests} failed requests):[/yellow]")
+        failed = network_data.get('failed_requests', {}).get('requests', [])
+        for req in failed[:3]:
+            console.print(f"   [yellow]{req.get('method')} {req.get('url')} → {req.get('status')}[/yellow]")
+
 def display_test_results(results: Dict):
-    """Display test results in rich format"""
+    """Display test results in rich format (legacy)"""
     
     # Summary table
     table = Table(title="Test Results Summary")

cursorflow/core/action_validator.py

@@ -0,0 +1,199 @@
+"""
+Action Format Validation
+
+Validates action dictionaries before execution to provide clear error messages.
+"""
+
+from typing import Dict, Any, List, Optional
+
+
+class ActionValidationError(Exception):
+    """Raised when action format is invalid"""
+    pass
+
+
+class ActionValidator:
+    """
+    Validates action format before execution
+    
+    Actions should be dictionaries with a single key indicating the action type,
+    or have an explicit 'type' key.
+    
+    Valid formats:
+        {"click": ".selector"}
+        {"click": {"selector": ".element"}}
+        {"type": "click", "selector": ".element"}
+        {"navigate": "/path"}
+        {"wait": 2}
+    """
+    
+    # CursorFlow-specific action types (not direct Playwright methods)
+    CURSORFLOW_ACTION_TYPES = {
+        'navigate', 'screenshot', 'capture', 'authenticate'
+    }
+    
+    # Common Playwright Page methods (for documentation/validation)
+    COMMON_PLAYWRIGHT_ACTIONS = {
+        'click', 'dblclick', 'hover', 'focus', 'blur',
+        'fill', 'type', 'press', 'select_option', 
+        'check', 'uncheck', 'set_checked',
+        'drag_and_drop', 'tap',
+        'wait', 'wait_for_selector', 'wait_for_timeout', 'wait_for_load_state',
+        'goto', 'reload', 'go_back', 'go_forward',
+        'scroll', 'set_viewport_size', 'bring_to_front',
+        'evaluate', 'evaluate_handle', 'query_selector'
+    }
+    
+    # All known valid actions (CursorFlow + Playwright)
+    # Note: This is not exhaustive - we pass through to Playwright dynamically
+    KNOWN_ACTION_TYPES = CURSORFLOW_ACTION_TYPES | COMMON_PLAYWRIGHT_ACTIONS
+    
+    @classmethod
+    def validate(cls, action: Any) -> Dict[str, Any]:
+        """
+        Validate action format and return normalized action
+        
+        Args:
+            action: The action to validate (should be dict)
+            
+        Returns:
+            Validated and normalized action dict
+            
+        Raises:
+            ActionValidationError: If action format is invalid
+        """
+        # Check if action is a dict
+        if not isinstance(action, dict):
+            raise ActionValidationError(
+                f"Action must be a dictionary, got {type(action).__name__}: {action}\n"
+                f"Expected format: {{'click': '.selector'}} or {{'type': 'click', 'selector': '.element'}}"
+            )
+        
+        # Check if action is empty
+        if not action:
+            raise ActionValidationError(
+                "Action dictionary is empty\n"
+                f"Expected format: {{'click': '.selector'}}"
+            )
+        
+        # Get action type
+        action_type = cls._extract_action_type(action)
+        
+        # Validate action type (permissive - warns for unknown, doesn't block)
+        if action_type not in cls.KNOWN_ACTION_TYPES:
+            # Log warning but allow it (might be valid Playwright method)
+            import logging
+            logger = logging.getLogger(__name__)
+            logger.warning(
+                f"Unknown action type '{action_type}' - will attempt to pass through to Playwright. "
+                f"Common actions: {', '.join(sorted(list(cls.COMMON_PLAYWRIGHT_ACTIONS)[:10]))}... "
+                f"See: https://playwright.dev/python/docs/api/class-page"
+            )
+        
+        return action
+    
+    @classmethod
+    def _extract_action_type(cls, action: dict) -> str:
+        """
+        Extract action type from action dict
+        
+        Supports:
+            {"type": "click", "selector": ".btn"}  # Explicit type key with string value
+            {"click": ".selector"}                  # Action type is the key
+            {"click": {"selector": ".btn"}}        # Action type with config dict
+            {"type": {"selector": "#field"}}       # 'type' as action (typing), not explicit type
+        """
+        # Check if 'type' key exists AND has a string value (explicit type specification)
+        # If type key has a dict value, it's the action itself (typing action)
+        if 'type' in action and isinstance(action['type'], str):
+            return action['type']
+        
+        # Otherwise, first key is the action type
+        keys = list(action.keys())
+        if not keys:
+            raise ActionValidationError("Action has no keys")
+        
+        action_type = keys[0]
+        
+        # First key should be the action type (string)
+        if not isinstance(action_type, str):
+            raise ActionValidationError(
+                f"Action type must be a string, got {type(action_type).__name__}: {action_type}"
+            )
+        
+        return action_type
+    
+    @classmethod
+    def validate_list(cls, actions: Any) -> List[Dict[str, Any]]:
+        """
+        Validate list of actions
+        
+        Args:
+            actions: Should be a list of action dicts
+            
+        Returns:
+            List of validated actions
+            
+        Raises:
+            ActionValidationError: If format is invalid
+        """
+        if not isinstance(actions, list):
+            raise ActionValidationError(
+                f"Actions must be a list, got {type(actions).__name__}: {actions}\n"
+                f"Expected format: [{{'click': '.btn'}}, {{'wait': 2}}]"
+            )
+        
+        if not actions:
+            raise ActionValidationError(
+                "Actions list is empty\n"
+                f"Expected at least one action like: [{{'navigate': '/'}}]"
+            )
+        
+        validated = []
+        for i, action in enumerate(actions):
+            try:
+                validated.append(cls.validate(action))
+            except ActionValidationError as e:
+                raise ActionValidationError(
+                    f"Invalid action at index {i}: {e}"
+                )
+        
+        return validated
+    
+    @classmethod
+    def get_example_actions(cls) -> str:
+        """Get example action formats for help text"""
+        return """
+Action Format Examples:
+
+  Common CursorFlow actions:
+    {"navigate": "/dashboard"}
+    {"click": ".button"}
+    {"screenshot": "page-loaded"}
+  
+  Any Playwright Page method:
+    {"hover": ".menu-item"}
+    {"dblclick": ".editable"}
+    {"press": "Enter"}
+    {"drag_and_drop": {"source": ".item", "target": ".dropzone"}}
+    {"focus": "#input"}
+    {"check": "#checkbox"}
+    {"evaluate": "window.scrollTo(0, 100)"}
+  
+  See full Playwright API:
+    https://playwright.dev/python/docs/api/class-page
+  
+  CursorFlow passes actions directly to Playwright, giving you access
+  to 94+ methods without artificial limitations.
+  
+  Complete workflow:
+    [
+      {"navigate": "/login"},
+      {"fill": {"selector": "#username", "value": "admin"}},
+      {"fill": {"selector": "#password", "value": "pass123"}},
+      {"click": "#submit"},
+      {"wait_for_selector": ".dashboard"},
+      {"screenshot": "logged-in"}
+    ]
+"""
+