cursorflow
Advanced tools
🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis
The measurement tool for web testing - we capture reality, not fiction
CursorFlow is a pure data collection engine that captures comprehensive web application intelligence. Unlike simulation tools that let you control reality, CursorFlow measures actual reality - giving you complete trust in your test results.
Other tools are simulation tools - they let you control reality:
CursorFlow is a measurement tool - we capture reality as-is:
CursorFlow is like a scientific instrument:
When CursorFlow reports "average_response_time": 416.58ms, you can tell stakeholders: "This is what actually happened" - not "this is what happened in our test simulation."
Complete Reliability: Every data point reflects real application behavior
Documentary vs Movie: Both are valuable, but if you're trying to understand reality, you watch the documentary. CursorFlow is the documentary of web testing.
CursorFlow doesn't limit you - it exposes the full power of Playwright:
94+ Playwright actions available:
# Any Playwright Page method works
cursorflow test --actions '[
{"hover": ".menu"},
{"dblclick": ".editable"},
{"press": "Enter"},
{"drag_and_drop": {"source": ".item", "target": ".zone"}},
{"check": "#checkbox"},
{"evaluate": "window.scrollTo(0, 500)"}
]'
Full configuration pass-through:
{
"browser_config": {
"browser_launch_options": {"devtools": true, "channel": "chrome"}
},
"context_options": {
"color_scheme": "dark",
"geolocation": {"latitude": 40.7128, "longitude": -74.0060},
"timezone_id": "America/Los_Angeles"
}
}
Forward-compatible: New Playwright features work immediately without CursorFlow updates.
See: Playwright API Documentation
CursorFlow generates valuable debugging data (screenshots, traces, sessions). Manage disk space:
# Clean old artifacts (>7 days)
cursorflow cleanup --artifacts --old-only
# Clean all artifacts
cursorflow cleanup --artifacts
# Clean saved sessions
cursorflow cleanup --sessions
# Clean everything
cursorflow cleanup --all
# Preview before deleting
cursorflow cleanup --all --dry-run
See: Complete Usage Guide
Test authenticated pages with automatic session management.
No configuration needed - just login with inline actions:
# Step 1: Login once and save session
cursorflow test --base-url http://localhost:3000 --actions '[
{"navigate": "/login"},
{"fill": {"selector": "#username", "value": "myuser"}},
{"fill": {"selector": "#password", "value": "mypass"}},
{"click": "#login-button"},
{"wait_for": ".dashboard"},
{"screenshot": "logged-in"}
]' --save-session "myuser"
# Step 2: Reuse session for all future tests (no re-login!)
cursorflow test --use-session "myuser" \
--path /admin/settings \
--screenshot "admin-panel"
# Step 3: Test another protected page
cursorflow test --use-session "myuser" \
--path /profile \
--screenshot "user-profile"
What's saved:
Session persists across tests - login once, test forever (until session expires).
For repeated testing, configure auth once in .cursorflow/config.json:
# 1. Configure auth in .cursorflow/config.json
{
"base_url": "http://localhost:3000",
"auth": {
"method": "form",
"username": "test@example.com",
"password": "testpass",
"username_selector": "#email",
"password_selector": "#password",
"submit_selector": "#login-button"
}
}
# 2. Login once and save session
cursorflow test --base-url http://localhost:3000 \
--path /login \
--save-session "user"
# 3. Reuse session for protected pages (no re-login!)
cursorflow test --use-session "user" \
--path /dashboard \
--screenshot "dashboard"
Supports:
SSO/OAuth Quick Start (Streamlined - No Manual Steps!):
# RECOMMENDED: Capture and save session in one command
cursorflow capture-auth --base-url http://localhost:3001 \
--path /dashboard \
--save-as-session "sso"
# Session is immediately ready to use!
cursorflow test --use-session "sso" --path /dashboard
# Or capture + test in one command:
cursorflow capture-auth --base-url http://localhost:3001 \
--path /dashboard \
--save-as-session "sso" \
--test-immediately
Features:
.cursorflow/sessions/sso_session.json (no manual copying!)--test-immediately validates session works--debug-session for troubleshootingTip: Use --browser chrome on macOS for better window visibility
See: Complete Authentication Guide
Every test captures everything needed for debugging:
# Clip to specific components
{"screenshot": {"name": "header", "options": {"clip": {"selector": "#header"}}}}
# Hide sensitive information
{"screenshot": {"name": "profile", "options": {"mask": [".user-email", ".api-key"]}}}
# Full page with quality control
{"screenshot": {"name": "page", "options": {"full_page": True, "quality": 90}}}
# Test across multiple viewports simultaneously
await flow.test_responsive([
{"width": 375, "height": 667, "name": "mobile"},
{"width": 768, "height": 1024, "name": "tablet"},
{"width": 1440, "height": 900, "name": "desktop"}
], [
{"navigate": "/dashboard"},
{"screenshot": "responsive-test"}
])
All data structured for AI consumption:
AI-Optimized Output with Complete Data Type Coverage - All CursorFlow features now organized for AI consumption:
# Test generates AI-optimized output automatically
cursorflow test --base-url http://localhost:3000 --path /app --logs local
# Query ANY data type instantly
cursorflow query session_123 --errors # Console errors
cursorflow query session_123 --server-logs # Server logs
cursorflow query session_123 --network --failed # Network failures
cursorflow query session_123 --screenshots # Screenshot index
cursorflow query session_123 --responsive # Responsive results
cursorflow query session_123 --css-iterations # CSS iterations
# Enhanced filtering
cursorflow query session_123 --errors --from-file "app.js" --contains "undefined"
cursorflow query session_123 --network --url-contains "/api/" --over 500ms
cursorflow query session_123 --server-logs --level error --pattern "database"
# Cross-referencing (time-based correlation)
cursorflow query session_123 --errors --with-network --with-server-logs
# Contextual queries
cursorflow query session_123 --context-for-error 2 --window 10
cursorflow query session_123 --group-by-url "/api/users"
# Enhanced comparison
cursorflow query session_A --compare-with session_B --errors
Impact:
Complete Data Coverage:
.cursorflow/artifacts/sessions/session_XXX/
├── server_logs.json # ⭐ Server-side logs (SSH/local/Docker)
├── errors.json # Browser console errors
├── network.json # Network requests/responses
├── screenshots.json # ⭐ Screenshot metadata
├── data_digest.md # AI summary (includes server logs)
└── + 6 more data files covering all CursorFlow features
| User Says | Command | What You Get |
|---|---|---|
| "Debug this error" | cursorflow test → query session_X --errors --with-network | Error + network + server logs correlated |
| "Fix this CSS" | Python: css_iteration_persistent() | Visual comparison of CSS variations |
| "Why is this slow?" | query session_X --network --over 500ms | Slow requests identified |
| "Test login flow" | cursorflow test --actions '[...]' | Complete flow with server correlation |
# User: "There's a JavaScript error on the dashboard"
# 1. Capture (5 seconds)
cursorflow test --base-url http://localhost:3000 --path /dashboard
# 2. Diagnose (10 seconds)
cat .cursorflow/artifacts/sessions/session_XXX/data_digest.md
cursorflow query session_XXX --errors
# 3. Get context (5 seconds)
cursorflow query session_XXX --context-for-error 0 --export markdown
# 4. Fix based on correlated data
# (You now have: error message, stack trace, network requests, server logs)
Total time: 20 seconds from problem to actionable diagnosis
"Error", "Broken", "Not working"
cursorflow test to capturequery --errors to identifyquery --context-for-error to understand"Slow", "Performance", "Takes forever"
cursorflow test to baselinequery --network --over 500ms to find bottlenecksquery --performance for metrics"CSS", "Styling", "Layout", "Spacing"
css_iteration_persistent()"Login", "Auth", "Session"
cursorflow test --actions '[...]' with login flow--save-session to preserve auth--use-session for subsequent testsquery --errors --contains "auth""Responsive", "Mobile", "Tablet"
cursorflow test --responsivequery --responsive --viewport mobile"Compare", "Regression", "What changed"
query session_before --compare-with session_afternew_errors and timing_changespip install cursorflow
playwright install chromium
cd /path/to/your/project
cursorflow install-rules
# Or skip prompts for automation/CI
cursorflow install-rules --yes
This creates:
.cursor/rules/ - Cursor AI integration rules.cursorflow/config.json - Project-specific configuration.cursorflow/ - Artifacts and session storage.gitignore entries for CursorFlow artifactsSimple page capture:
cursorflow test --base-url http://localhost:3000 --path /dashboard
Interactive testing with inline actions:
cursorflow test --base-url http://localhost:3000 \
--path /messages \
--wait-for ".message-item" \
--hover ".message-item:first-child" \
--click ".message-item:first-child" \
--screenshot "clicked" \
--show-console \
--open-trace
# Full page screenshot (captures entire scrollable content)
cursorflow test --base-url http://localhost:3000 \
--path /dashboard \
--screenshot "complete-page" \
--full-page
Custom actions with JSON:
cursorflow test --base-url http://localhost:3000 --actions '[
{"navigate": "/login"},
{"fill": {"selector": "#email", "value": "test@example.com"}},
{"click": "#login-btn"},
{"screenshot": {"name": "result", "options": {"mask": [".sensitive-data"]}}}
]'
from cursorflow import CursorFlow
async def capture_reality():
flow = CursorFlow("http://localhost:3000", {"source": "local", "paths": ["logs/app.log"]})
# Capture everything
results = await flow.execute_and_collect([
{"navigate": "/dashboard"},
{"screenshot": "complete-analysis"}
])
# Access comprehensive data
screenshot = results['artifacts']['screenshots'][0]
print(f"Real load time: {screenshot['performance_data']['page_load_time']}ms")
print(f"Actual memory usage: {screenshot['performance_data']['memory_usage_mb']}MB")
print(f"Elements found: {len(screenshot['dom_analysis']['elements'])}")
# Component-focused testing
await flow.execute_and_collect([
{"navigate": "/components"},
{"screenshot": {
"name": "button-component",
"options": {"clip": {"selector": ".component-demo"}}
}}
])
# Privacy-aware testing
await flow.execute_and_collect([
{"navigate": "/admin"},
{"screenshot": {
"name": "admin-safe",
"options": {
"full_page": True,
"mask": [".api-key", ".user-data", ".sensitive-info"]
}
}}
])
# Perfect CSS iteration timing
async def hmr_workflow():
flow = CursorFlow("http://localhost:5173", {"headless": False})
# Auto-detect and monitor HMR
await flow.browser.start_hmr_monitoring()
# Baseline capture
await flow.execute_and_collect([{"screenshot": "baseline"}])
# Wait for real CSS changes with perfect timing
hmr_event = await flow.browser.wait_for_css_update()
print(f"🔥 {hmr_event['framework']} detected real change!")
# Capture immediately after actual change
await flow.execute_and_collect([{"screenshot": "updated"}])
# Test responsive design across multiple viewports
async def test_responsive_design():
flow = CursorFlow("http://localhost:3000", {"source": "local", "paths": ["logs/app.log"]})
# Define viewports
viewports = [
{"width": 375, "height": 667, "name": "mobile"},
{"width": 768, "height": 1024, "name": "tablet"},
{"width": 1440, "height": 900, "name": "desktop"}
]
# Test same actions across all viewports
results = await flow.test_responsive(viewports, [
{"navigate": "/dashboard"},
{"click": "#menu-toggle"},
{"screenshot": {"name": "navigation", "options": {"clip": {"selector": "#nav"}}}}
])
# Analyze responsive behavior
print(f"Tested {results['execution_summary']['successful_viewports']} viewports")
print(f"Fastest: {results['responsive_analysis']['performance_analysis']['fastest_viewport']}")
1. Inline CLI Flags (use = separator for fill):
cursorflow test --base-url http://localhost:3000 \
--path /login \
--fill "#email=test@example.com" \
--fill "#password=mypass" \
--click "button[type='submit']" \
--screenshot "result"
2. JSON Actions (use dict with selector and value):
cursorflow test --base-url http://localhost:3000 --actions '[
{"navigate": "/login"},
{"fill": {"selector": "#email", "value": "test@example.com"}},
{"fill": {"selector": "#password", "value": "mypass"}},
{"click": "button[type=\"submit\"]"},
{"screenshot": "result"}
]'
❌ Don't mix formats! Using | or = inside JSON actions won't work.
# Simple page test with complete intelligence
cursorflow test --base-url http://localhost:3000 --path "/dashboard"
# Responsive testing across multiple viewports
cursorflow test --base-url http://localhost:3000 --path "/dashboard" --responsive
# Complex interaction testing
cursorflow test --base-url http://localhost:3000 --actions '[
{"navigate": "/form"},
{"fill": {"selector": "#name", "value": "Test User"}},
{"click": "#submit"},
{"screenshot": {"name": "result", "options": {"clip": {"selector": ".result-area"}}}}
]'
# Responsive testing with custom actions
cursorflow test --base-url http://localhost:3000 --responsive --actions '[
{"navigate": "/products"},
{"fill": {"selector": "#search", "value": "laptop"}},
{"screenshot": "search-results"}
]'
# Custom output location
cursorflow test --base-url http://localhost:3000 --path "/api" --output "api-test-results.json"
# Inline action flags
cursorflow test --base-url http://localhost:3000 \
--path /dashboard \
--screenshot "full-page-capture" \
--full-page # Captures entire scrollable page
# Compare mockup to implementation - get similarity metrics
cursorflow compare-mockup https://mockup.com/design \
--base-url http://localhost:3000 \
--implementation-actions '[{"navigate": "/dashboard"}]'
# Output: 87.3% similarity, diff images, element measurements
# Test CSS variations - observe real rendering
cursorflow iterate-mockup https://mockup.com/design \
--base-url http://localhost:5173 \
--css-improvements '[
{"name": "spacing-fix", "css": ".container { gap: 2rem; }"},
{"name": "tighter-spacing", "css": ".container { gap: 1rem; }"}
]'
# Output: Similarity data for each variation (Cursor decides which to apply)
# Comprehensive element inspection with full CSS analysis
cursorflow inspect --base-url http://localhost:3000 --selector "#messages-panel"
# Show all computed CSS properties
cursorflow inspect -u http://localhost:3000 -s ".card" --verbose
# Quick dimension check (surgical precision)
cursorflow measure --base-url http://localhost:3000 --selector "#panel"
# Measure multiple elements at once
cursorflow measure -u http://localhost:3000 -s "#panel1" -s "#panel2"
# Verify CSS changes with all properties
cursorflow measure -u http://localhost:3000 -s ".button" --verbose
# Install Cursor AI rules
cursorflow install-rules
# Update to latest version and rules
cursorflow update
Universal Compatibility:
HMR Auto-Detection:
"We let you mock and simulate"
"We tell you the truth"
When you need to understand reality, choose the measurement tool - not the simulation tool.
Complete page intelligence • Real behavior measurement • AI-first design • Pure observation
FAQs
🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis
We found that cursorflow demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins 10 Minutes or Less, a podcast by Ali Rohde, to discuss the recent surge in open source supply chain attacks.
Research
/Security News
Campaign of 108 extensions harvests identities, steals sessions, and adds backdoors to browsers, all tied to the same C2 infrastructure.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.