cursorflow 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,444 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: cursorflow
3
- Version: 1.2.0
4
- Summary: AI-guided universal UI testing framework that adapts to any web architecture
5
- Author-email: GeekWarrior Development <support@cursorflow.dev>
6
- License: MIT
7
- Project-URL: Homepage, https://github.com/haley-marketing-group/cursorflow
8
- Project-URL: Documentation, https://cursorflow.readthedocs.io
9
- Project-URL: Repository, https://github.com/haley-marketing-group/cursorflow
10
- Keywords: ui-testing,automation,cursor,ai,web-testing,css-iteration
11
- Classifier: Development Status :: 5 - Production/Stable
12
- Classifier: Intended Audience :: Developers
13
- Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Programming Language :: Python :: 3
15
- Classifier: Programming Language :: Python :: 3.8
16
- Classifier: Programming Language :: Python :: 3.9
17
- Classifier: Programming Language :: Python :: 3.10
18
- Classifier: Programming Language :: Python :: 3.11
19
- Classifier: Programming Language :: Python :: 3.12
20
- Classifier: Topic :: Software Development :: Testing
21
- Classifier: Topic :: Software Development :: Quality Assurance
22
- Classifier: Framework :: AsyncIO
23
- Requires-Python: >=3.8
24
- Description-Content-Type: text/markdown
25
- Requires-Dist: playwright>=1.40.0
26
- Requires-Dist: paramiko>=3.3.1
27
- Requires-Dist: pyyaml>=6.0.1
28
- Requires-Dist: asyncio-mqtt>=0.11.1
29
- Requires-Dist: click>=8.1.7
30
- Requires-Dist: rich>=13.6.0
31
- Requires-Dist: jinja2>=3.1.2
32
- Requires-Dist: python-dateutil>=2.8.2
33
- Requires-Dist: watchdog>=3.0.0
34
- Requires-Dist: docker>=6.1.3
35
- Provides-Extra: dev
36
- Requires-Dist: pytest>=7.4.0; extra == "dev"
37
- Requires-Dist: pytest-asyncio>=0.21.1; extra == "dev"
38
- Requires-Dist: black>=23.9.1; extra == "dev"
39
- Requires-Dist: flake8>=6.1.0; extra == "dev"
40
- Requires-Dist: mypy>=1.6.1; extra == "dev"
41
-
42
- # CursorFlow 🔥
43
-
44
- **Ultra-fast CSS iteration engine with hot reload integration for Cursor AI**
45
-
46
- CursorFlow is a universal UI testing framework optimized for rapid CSS development and debugging. It automatically detects and leverages hot reload environments to enable **3-5x faster CSS iteration cycles** while preserving application state.
47
-
48
- ## 🚀 What CursorFlow Does
49
-
50
- ### **CSS Iteration with Hot Reload**
51
- - **Persistent browser sessions** that survive between CSS changes
52
- - **Automatic hot reload detection** (webpack HMR, Vite, Next.js, etc.)
53
- - **Instant CSS application** without page reloads or lost state
54
- - **Real-time visual feedback** with comprehensive screenshots and metrics
55
-
56
- ### **Universal UI Testing**
57
- - Browser automation actions (navigate, click, fill forms, take screenshots)
58
- - Server log monitoring and correlation with browser events
59
- - Cross-framework error detection and debugging
60
- - Structured data output optimized for Cursor AI analysis
61
-
62
- ### **Intelligent Session Management**
63
- - Smart session lifecycle with automatic cleanup
64
- - File change monitoring and hot reload synchronization
65
- - Performance analytics and optimization recommendations
66
- - Framework-agnostic hot reload support
67
-
68
- ## Installation
69
-
70
- ```bash
71
- pip install cursorflow
72
- ```
73
-
74
- ### Dependencies
75
- CursorFlow will automatically install browser dependencies on first use. To install manually:
76
-
77
- ```bash
78
- playwright install chromium
79
- ```
80
-
81
- ## 🔥 Quick Start - Hot Reload CSS Iteration
82
-
83
- ### 1. **Ultra-Fast CSS Iteration (Recommended)**
84
- ```python
85
- from cursorflow import CursorFlow
86
-
87
- # Initialize with hot reload support
88
- flow = CursorFlow(
89
- base_url="http://localhost:3000", # Your dev server
90
- log_config={"source": "local", "paths": ["logs/app.log"]},
91
- browser_config={"hot_reload_enabled": True, "keep_alive": True}
92
- )
93
-
94
- # CSS changes to test rapidly
95
- css_changes = [
96
- {
97
- "name": "improve-spacing",
98
- "css": ".container { gap: 2rem; padding: 1.5rem; }",
99
- "rationale": "Better visual hierarchy"
100
- },
101
- {
102
- "name": "add-shadows",
103
- "css": ".card { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }",
104
- "rationale": "Add depth and visual interest"
105
- }
106
- ]
107
-
108
- # Execute with persistent session - 3-5x faster than normal!
109
- results = await flow.css_iteration_persistent(
110
- base_actions=[{"navigate": "/dashboard"}, {"wait_for": "#main-content"}],
111
- css_changes=css_changes,
112
- session_options={"hot_reload": True, "keep_session_alive": True}
113
- )
114
-
115
- # Check results
116
- print(f"🔥 Hot reload used: {results.get('hot_reload_used')}")
117
- print(f"⚡ Iterations per minute: {results.get('persistent_analysis', {}).get('iteration_speed_metrics', {}).get('iterations_per_minute', 0):.1f}")
118
- ```
119
-
120
- ### 2. **CLI Usage (Traditional)**
121
- ```bash
122
- # Initialize project configuration
123
- cursorflow init .
124
-
125
- # Quick component test
126
- cursorflow test dashboard-component \
127
- --actions '[
128
- {"navigate": "/dashboard"},
129
- {"wait_for": "#main-content"},
130
- {"screenshot": "dashboard-loaded"}
131
- ]' \
132
- --base-url http://localhost:3000
133
- ```
134
-
135
- ### 3. **Session Continuation (No Page Reload!)**
136
- ```python
137
- # First iteration - sets up persistent session
138
- results1 = await flow.css_iteration_persistent(
139
- base_actions=[{"navigate": "/page"}],
140
- css_changes=[{"name": "initial", "css": ".container { display: flex; }"}],
141
- session_options={"session_id": "my_session", "keep_session_alive": True}
142
- )
143
-
144
- # Continue with same session - INSTANT feedback!
145
- results2 = await flow.css_iteration_persistent(
146
- base_actions=[], # No base actions needed - session preserved!
147
- css_changes=[{"name": "refine", "css": ".container { gap: 1rem; }"}],
148
- session_options={"session_id": "my_session", "reuse_session": True}
149
- )
150
- ```
151
-
152
- ## 🔥 Hot Reload Framework Support
153
-
154
- CursorFlow automatically detects and optimizes for:
155
-
156
- | Framework | Hot Reload Type | Speed Boost | Auto-Detection |
157
- |-----------|----------------|-------------|----------------|
158
- | **Webpack HMR** | Hot Module Replacement | 5x faster | ✅ Automatic |
159
- | **Vite** | Lightning HMR | 5x faster | ✅ Automatic |
160
- | **Next.js** | Fast Refresh | 4x faster | ✅ Automatic |
161
- | **Create React App** | React Hot Reload | 4x faster | ✅ Automatic |
162
- | **Vue CLI** | Vue HMR | 4x faster | ✅ Automatic |
163
- | **Angular CLI** | Angular HMR | 3x faster | ✅ Automatic |
164
-
165
- ### **Benefits of Hot Reload Integration**
166
- - ⚡ **3-5x faster CSS iterations** compared to full page reloads
167
- - 🎯 **Preserved application state** during styling changes
168
- - 🔥 **Instant visual feedback** without interrupting user flows
169
- - 🧠 **Intelligent session management** with automatic optimization
170
- - 📊 **Performance analytics** to track iteration efficiency
171
-
172
- ## CLI Commands
173
-
174
- ### test
175
- Run UI test sequence and collect data.
176
-
177
- ```bash
178
- cursorflow test [TEST_NAME] [OPTIONS]
179
- ```
180
-
181
- **Options:**
182
- - `--actions`: JSON file or inline JSON string with test actions
183
- - `--base-url`: Base URL for testing (default: http://localhost:3000)
184
- - `--logs`: Log source type (local, ssh, docker, systemd)
185
- - `--config`: Configuration file path
186
- - `--verbose`: Show detailed output
187
-
188
- ### init
189
- Initialize CursorFlow configuration in a project.
190
-
191
- ```bash
192
- cursorflow init PROJECT_PATH
193
- ```
194
-
195
- ### install-rules
196
- Install Cursor AI rules for CursorFlow usage.
197
-
198
- ```bash
199
- cursorflow install-rules
200
- ```
201
-
202
- ### update
203
- Update CursorFlow package and rules.
204
-
205
- ```bash
206
- cursorflow update
207
- ```
208
-
209
- ## Available Actions
210
-
211
- ### **CSS Iteration Actions (Hot Reload Optimized)**
212
- | Action | Purpose | Syntax |
213
- |--------|---------|--------|
214
- | `css_iteration_persistent` | Ultra-fast CSS testing with hot reload | `await flow.css_iteration_persistent(base_actions, css_changes, session_options)` |
215
- | `session_continuation` | Continue existing session without reload | `session_options={"session_id": "my_session", "reuse_session": True}` |
216
- | `hot_reload_detection` | Automatic framework detection | Automatic - works with Webpack, Vite, Next.js, etc. |
217
-
218
- ### **Standard Browser Actions**
219
- | Action | Purpose | Syntax |
220
- |--------|---------|--------|
221
- | `navigate` | Go to URL/path | `{"navigate": "/dashboard"}` |
222
- | `click` | Click element | `{"click": "#button"}` |
223
- | `fill` | Fill input field | `{"fill": {"selector": "#email", "value": "test@example.com"}}` |
224
- | `wait` | Wait seconds | `{"wait": 2}` |
225
- | `wait_for` | Wait for element | `{"wait_for": "#results"}` |
226
- | `screenshot` | Take screenshot | `{"screenshot": "page-state"}` |
227
-
228
- 📚 **Complete Documentation:**
229
- - [Hot Reload Guide](docs/user/HOT_RELOAD_GUIDE.md) - Comprehensive hot reload usage
230
- - [Action System](docs/user/ACTION_SYSTEM.md) - All available actions
231
- - [CSS Iteration Examples](examples/hot_reload_css_iteration.py) - Working code examples
232
-
233
- ## Configuration
234
-
235
- ### **Hot Reload Optimized Configuration**
236
-
237
- ```json
238
- {
239
- "environments": {
240
- "local": {
241
- "base_url": "http://localhost:3000",
242
- "log_paths": {
243
- "app": "logs/app.log",
244
- "dev_server": ".next/trace.log"
245
- },
246
- "hot_reload": {
247
- "enabled": true,
248
- "framework": "auto-detect",
249
- "file_monitoring": true
250
- }
251
- }
252
- },
253
- "browser": {
254
- "headless": false,
255
- "hot_reload_enabled": true,
256
- "keep_alive": true,
257
- "debug_mode": true,
258
- "timeout": 30000
259
- },
260
- "session_management": {
261
- "max_sessions": 5,
262
- "session_timeout": 3600,
263
- "auto_cleanup": true
264
- },
265
- "auth": {
266
- "method": "form",
267
- "username_selector": "#username",
268
- "password_selector": "#password",
269
- "submit_selector": "#login-button"
270
- }
271
- }
272
- ```
273
-
274
- ### **Quick Configuration for Popular Frameworks**
275
-
276
- **Next.js/React:**
277
- ```json
278
- {
279
- "environments": {
280
- "local": {
281
- "base_url": "http://localhost:3000",
282
- "log_paths": {"app": ".next/trace.log"},
283
- "hot_reload": {"framework": "nextjs"}
284
- }
285
- }
286
- }
287
- ```
288
-
289
- **Vite:**
290
- ```json
291
- {
292
- "environments": {
293
- "local": {
294
- "base_url": "http://localhost:5173",
295
- "hot_reload": {"framework": "vite"}
296
- }
297
- }
298
- }
299
- ```
300
-
301
- ## Output
302
-
303
- ### **Enhanced Hot Reload Results**
304
-
305
- CursorFlow generates comprehensive analysis optimized for Cursor AI:
306
-
307
- ```json
308
- {
309
- "session_id": "css_session_20240925_134401",
310
- "success": true,
311
- "hot_reload_used": true,
312
- "execution_time": 4.2,
313
-
314
- "session_context": {
315
- "session_persistent": true,
316
- "hot_reload_available": true,
317
- "session_age_seconds": 1200,
318
- "iteration_count": 15
319
- },
320
-
321
- "persistent_analysis": {
322
- "hot_reload_effectiveness": {
323
- "hot_reload_usage_rate": 0.95,
324
- "time_saved_seconds": 45.2,
325
- "quality": "excellent"
326
- },
327
- "iteration_speed_metrics": {
328
- "iterations_per_minute": 12.5,
329
- "average_iteration_time": 4.8
330
- }
331
- },
332
-
333
- "iterations": [
334
- {
335
- "name": "improve-spacing",
336
- "hot_reload_used": true,
337
- "screenshot": ".cursorflow/artifacts/improve-spacing.png",
338
- "console_errors": [],
339
- "performance_impact": {"render_time": 45}
340
- }
341
- ],
342
-
343
- "session_management": {
344
- "recommended_action": "continue_session_optimal",
345
- "keep_session_alive": true,
346
- "next_iteration_strategy": "continue_with_hot_reload"
347
- },
348
-
349
- "recommended_actions": [
350
- {
351
- "action": "implement_css_changes",
352
- "css_to_apply": ".container { gap: 2rem; }",
353
- "target_files": ["components/Dashboard.css"],
354
- "benefits": ["Faster iterations", "Maintained state"]
355
- }
356
- ]
357
- }
358
- ```
359
-
360
- ### **Traditional Test Output**
361
- ```json
362
- {
363
- "session_id": "test_20240925_134401",
364
- "browser_events": [...],
365
- "server_logs": [...],
366
- "organized_timeline": [...],
367
- "artifacts": {
368
- "screenshots": ["login-page.png", "after-login.png"]
369
- }
370
- }
371
- ```
372
-
373
- ## Log Sources
374
-
375
- CursorFlow can monitor various log sources:
376
-
377
- - **Local files**: `--logs local` (default)
378
- - **SSH remote**: `--logs ssh` (requires SSH config in cursor-test-config.json)
379
- - **Docker containers**: `--logs docker`
380
- - **System logs**: `--logs systemd`
381
-
382
- ## Updates
383
-
384
- Check for updates:
385
- ```bash
386
- cursorflow check-updates
387
- ```
388
-
389
- Update to latest version:
390
- ```bash
391
- cursorflow update
392
- ```
393
-
394
- CursorFlow automatically checks for updates when used in projects.
395
-
396
- ## Requirements
397
-
398
- - Python 3.8+
399
- - Chromium browser (installed automatically via Playwright)
400
- - Network access to target application
401
-
402
- ## Project Structure
403
-
404
- ```
405
- cursorflow/
406
- ├── artifacts/ # Test artifacts and screenshots
407
- ├── config/ # Example configuration files
408
- ├── cursorflow/ # Main package source code
409
- │ ├── core/ # Core testing engine
410
- │ └── log_sources/ # Log monitoring implementations
411
- ├── docs/ # Complete documentation
412
- │ ├── api/ # API specifications
413
- │ ├── development/ # Development guides
414
- │ ├── examples/ # Usage examples
415
- │ ├── product/ # Product requirements
416
- │ └── user/ # User guides
417
- ├── examples/ # Code examples
418
- ├── rules/ # Cursor AI integration rules
419
- ├── scripts/ # Release and automation scripts
420
- └── tests/ # Test suite
421
- ```
422
-
423
- ## 📚 Documentation
424
-
425
- ### **🔥 Hot Reload & CSS Iteration**
426
- - **[Hot Reload Guide](docs/user/HOT_RELOAD_GUIDE.md)** - Complete guide to ultra-fast CSS iteration
427
- - **[CSS Iteration Examples](examples/hot_reload_css_iteration.py)** - Working code examples
428
- - **[Framework Integration](docs/user/FRAMEWORK_INTEGRATION.md)** - Webpack, Vite, Next.js setup
429
-
430
- ### **📖 Complete Guides**
431
- - **[Getting Started](docs/user/GETTING_STARTED.md)** - Installation and basic usage
432
- - **[Usage Guide](docs/user/USAGE_GUIDE.md)** - Comprehensive usage patterns
433
- - **[Action System](docs/user/ACTION_SYSTEM.md)** - All available actions and syntax
434
- - **[Examples](examples/)** - Real-world code examples and workflows
435
-
436
- ### **🔧 Development & API**
437
- - **[API Reference](docs/api/)** - Complete API documentation
438
- - **[Development Guide](docs/development/)** - Contributing and releases
439
- - **[Implementation Details](docs/development/IMPLEMENTATION_ROADMAP.md)** - Technical architecture
440
-
441
- ## Support
442
-
443
- - Issues: [GitHub Issues](https://github.com/haley-marketing-group/cursorflow/issues)
444
- - Repository: [haley-marketing-group/cursorflow](https://github.com/haley-marketing-group/cursorflow)