Skip to content

Commit af71d28

Browse files
nirukk52nirukk52
committed
feat: BrowserStack migration and auto-device-provision
- Add BrowserStack app upload adapter and cloud storage port - Update EnsureDevice node to support BrowserStack lifecycle - Add session cleanup in Stop node handler for BrowserStack - Update ProvisionApp node with BrowserStack session support - Improve dev log monitoring skill documentation - Update run types and context nodes for BrowserStack integration - Add BrowserStack migration documentation and summary - Update E2E tests and frontend env config for BrowserStack - Add mcp.json to .gitignore (contains secrets)
1 parent b57408e commit af71d28

File tree

29 files changed

+1629
-390
lines changed

29 files changed

+1629
-390
lines changed

‎.claude-skills/dev-log-monitoring_skill/SKILL.md‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,12 +77,26 @@ curl -s http://localhost:5173 | head -n 1
7777

7878
## Step 2: Navigate and Execute Flow with Playwright MCP
7979

80+
### 2.0 Close Existing Browser Session (MANDATORY)
81+
82+
**ALWAYS close any existing browser tabs first to avoid "about:blank" issues:**
83+
84+
```
85+
# List existing tabs
86+
mcp_cursor-browser-extension_browser_tabs(action: "list")
87+
88+
# Close all tabs
89+
mcp_cursor-browser-extension_browser_tabs(action: "close", index: 0)
90+
```
91+
92+
Repeat until no tabs remain. This prevents stale browser state and ensures clean test execution.
93+
8094
### 2.1 Navigate to Application
8195

8296
Use Playwright MCP to open the app:
8397

8498
```
85-
mcp_playwright_browser_navigate(url: "http://localhost:5173")
99+
mcp_cursor-browser-extension_browser_navigate(url: "http://localhost:5173")
86100
```
87101

88102
### 2.2 Trigger Drift Detection
@@ -405,6 +419,50 @@ curl -s http://localhost:4000/graph/diagnostics
405419
grep "agent.event.screen_perceived" /tmp/backend-logs.txt
406420
```
407421

422+
### BrowserStack Session Issues
423+
424+
**Symptom:** Agent times out during ProvisionApp or EnsureDevice with BrowserStack
425+
426+
**Check:**
427+
```bash
428+
# Look for BrowserStack session creation
429+
grep "Creating Appium session" /tmp/backend-logs.txt | grep browserStack
430+
431+
# Check for timeout errors
432+
grep -i "timeout\|timed out" /tmp/backend-logs.txt | grep -i browserstack
433+
434+
# Verify device name
435+
grep "deviceName" /tmp/backend-logs.txt | tail -5
436+
```
437+
438+
**Debug with BrowserStack MCP:**
439+
```bash
440+
# Check recent sessions
441+
curl -s -u "USERNAME:KEY" "https://api-cloud.browserstack.com/app-automate/builds.json?limit=3"
442+
443+
# Get session details (replace SESSION_ID)
444+
curl -s -u "USERNAME:KEY" "https://api-cloud.browserstack.com/app-automate/builds/BUILD_ID/sessions/SESSION_ID.json"
445+
446+
# Check available devices
447+
curl -s -u "USERNAME:KEY" "https://api-cloud.browserstack.com/app-automate/devices.json" | grep "Samsung\|Pixel"
448+
```
449+
450+
**Common Fixes:**
451+
1. **Invalid device name**: Query available devices via API - names are account-specific and case-sensitive
452+
2. **Missing APK upload**: Pre-upload APK in buildAgentContext, pass `bs://` URL to session (CRITICAL)
453+
3. **Session not closed**: Add `driver.deleteSession()` in Stop node handler
454+
4. **Timeout issues**: 60s default is sufficient (BrowserStack completes in ~40s)
455+
456+
**Artifact Locations:**
457+
```bash
458+
# Screenshots and UI XML stored by Encore
459+
ls -la ~/Library/Caches/encore/objects/*/artifacts/obj:/artifacts/[RUN_ID]/screenshot/
460+
ls -la ~/Library/Caches/encore/objects/*/artifacts/obj:/artifacts/[RUN_ID]/ui_xml/
461+
462+
# Open most recent screenshot
463+
open "$(find ~/Library/Caches/encore/objects/*/artifacts/ -name "*.png" | tail -1)"
464+
```
465+
408466
## Resources
409467

410468
### references/log_patterns.md

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,3 +149,8 @@ out
149149
# Skills (Local Development Only)
150150
# ============================================
151151
skills-main/
152+
153+
# ============================================
154+
# MCP Configuration (Contains Secrets)
155+
# ============================================
156+
mcp.json

‎BROWSERSTACK_MIGRATION_SUMMARY.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# ✅ BrowserStack Migration Complete
2+
3+
**Date**: 2025-11-15
4+
**Branch**: `005-auto-device-provision`
5+
**Status**: Ready for testing
6+
7+
---
8+
9+
## What Changed
10+
11+
Replaced **local Appium + local devices** with **BrowserStack cloud device management**.
12+
13+
### Before (Spec 001)
14+
- Manual Appium server management
15+
- Local device setup (USB, ADB)
16+
- Device prerequisite checks
17+
- 60s Appium startup timeout
18+
19+
### After (BrowserStack)
20+
- ✅ Managed cloud Appium
21+
- ✅ Cloud devices (no USB needed)
22+
- ✅ No local prerequisites
23+
- ✅ Instant availability
24+
- ✅ CI/CD ready
25+
26+
---
27+
28+
## Required Setup
29+
30+
Add these credentials to your `.env` file:
31+
32+
```bash
33+
# BrowserStack Credentials (REQUIRED)
34+
BROWSERSTACK_USERNAME=your_username_here
35+
BROWSERSTACK_ACCESS_KEY=your_access_key_here
36+
37+
# Optional (has default)
38+
BROWSERSTACK_HUB_URL=https://hub.browserstack.com/wd/hub
39+
```
40+
41+
**Get credentials from**: Your BrowserStack account dashboard
42+
43+
---
44+
45+
## Files Modified
46+
47+
1. ✅ `backend/config/env.ts` - Added 3 BrowserStack env vars
48+
2. ✅ `backend/agent/nodes/setup/EnsureDevice/appium-lifecycle.ts` - Removed local server management
49+
3. ✅ `backend/agent/nodes/setup/EnsureDevice/node.ts` - Simplified to hub health check only
50+
4. ✅ `backend/agent/adapters/appium/webdriverio/session.adapter.ts` - Added HTTPS/path support
51+
5. ✅ `specs/001-automate-appium-lifecycle/BROWSERSTACK_MIGRATION.md` - Full migration docs
52+
53+
---
54+
55+
## Deprecated Specs
56+
57+
- ⚠️ **Spec 001** (automate-appium-lifecycle) - No longer needed
58+
- ⚠️ **Spec 005** (auto-device-provision) - BrowserStack handles this
59+
60+
---
61+
62+
## Testing Next Steps
63+
64+
1. **Set credentials in `.env`** (see above)
65+
2. **Start backend**: `cd backend && encore run`
66+
3. **Verify health check**: Look for "browserstack hub is healthy" in logs
67+
4. **Start a run**: Device session should connect to BrowserStack
68+
5. **Monitor logs**: Check for `actor: "browserstack-lifecycle"` entries
69+
70+
---
71+
72+
## Architecture Summary
73+
74+
```
75+
Before:
76+
User → Start Run → EnsureDevice → Check ADB → Start Appium → Connect Device → Run Agent
77+
78+
After:
79+
User → Start Run → EnsureDevice → Check BrowserStack Hub → Connect Cloud Device → Run Agent
80+
```
81+
82+
**Key Difference**: No local infrastructure required. Everything runs in the cloud.
83+
84+
---
85+
86+
## Documentation
87+
88+
- **Full Migration Guide**: `specs/001-automate-appium-lifecycle/BROWSERSTACK_MIGRATION.md`
89+
- **Graphiti Memory**: Added to `group_id="screengraph"` with tags: `backend`, `agent`, `browserstack`, `spec-001-deprecated`
90+
91+
---
92+
93+
## Need Help?
94+
95+
**Q: Where do I get BrowserStack credentials?**
96+
A: From your BrowserStack account dashboard or contact project owner
97+
98+
**Q: Will runs still work with local devices?**
99+
A: No. System is now BrowserStack-only. No local Appium support.
100+
101+
**Q: What if BrowserStack is down?**
102+
A: Runs will fail with `BrowserStackUnavailableError` (retryable)
103+
104+
**Q: How do I test locally during development?**
105+
A: Use BrowserStack's cloud devices. No local testing supported.
106+
107+
---
108+
109+
**Ready to test!** 🚀
110+
111+
Set your credentials and run: `cd backend && encore run`
112+

‎FOUNDERS_NOTEPAD.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,4 +86,6 @@ Labels & Notes – Tag screens (“Paywall”, “KYC”), leave short reviews,
8686

8787

8888
Helpful commands
89-
open "/Users/priyankalalge/Library/Caches/encore/objects/d3u8d93djnh82bnf6l1g/artifacts/obj:/artifacts/"
89+
open "/Users/priyankalalge/Library/Caches/encore/objects/d3u8d93djnh82bnf6l1g/artifacts/obj:/artifacts/"
90+
91+
https://developer.android.com/training/testing/ui-tests/screenshot

‎backend/agent/README.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,92 @@
1+
# ONE GIANT MAP — TECH STACK + CLOUD + NODES + BUSINESS VALUE
2+
3+
+-----------------------------------------------------------------------------------------------------------------+
4+
| BUSINESS LAYER |
5+
| * Primary Use-Cases * |
6+
| - Full automated mobile QA |
7+
| - Visual regression + drift detection |
8+
| - Competitive analysis (auto-mapping competitor apps) |
9+
| - CI/CD blocking on UX changes |
10+
| - Product insights: new flows, abandoned paths, UX stability |
11+
| - Release-over-release diff timelines |
12+
| - PM-facing screen explorer dashboards |
13+
| - Engineering reproducible bug reports |
14+
| |
15+
| * Stakeholders * |
16+
| - QA Teams | Product Managers | Founders | Designers | Analysts |
17+
+-----------------------------------------------------------------------------------------------------------------+
18+
|
19+
v
20+
+-----------------------------------------------------------------------------------------------------------------+
21+
| CLOUD DEVICE PROVIDERS |
22+
| (Execution backend for ACT + PERCEIVE) |
23+
| - AWS Device Farm: real devices, parallel runs, screenshots, videos |
24+
| - BrowserStack App Automate: instant devices, Appium endpoints |
25+
| - Sauce Labs: automated mobile flows + advanced debugging |
26+
| |
27+
| All feed into: ScreenGraph DriverPort → Perceive → Act |
28+
+-----------------------------------------------------------------------------------------------------------------+
29+
|
30+
v
31+
+-----------------------------------------------------------------------------------------------------------------+
32+
| TOOLING + ANALYSIS LAYER |
33+
| *Dynamic Crawlers & Fuzzers* |
34+
| - DroidBot, DroidRun, Fastbot, Stoat, Ape, Monkey, MarlonTool, DroidMate |
35+
| *State/Model Extractors* |
36+
| - Gator, DroidFax, FlowDroid |
37+
| *Runtime Introspection Tools* |
38+
| - Stetho, Flipper, Facebook Infer |
39+
| *APK / XML Processing* |
40+
| - Apktool, AXMLPrinter2, uiautomatorviewer |
41+
| *LLM / AI Engines* |
42+
| - Humanoid, GPT/LLM-based Explorers |
43+
| |
44+
| Role: Enrich ENUMERATE / CHOOSE / VERIFY / PERSIST / DETECTPROGRESS |
45+
+-----------------------------------------------------------------------------------------------------------------+
46+
|
47+
v
48+
+-----------------------------------------------------------------------------------------------------------------+
49+
| CORE SCREENGRAPH ENGINE |
50+
| State-Space Engine: |
51+
| - ScreenGraph (screenId ↔ hash) |
52+
| - ActionGraph (edges) |
53+
| - Coverage metrics (screens, edges, paths) |
54+
| - Loop detection, stall scoring |
55+
| |
56+
| Visual Engine: |
57+
| - Perceptual hashing (pHash/dHash/SSIM) |
58+
| - Pixel diffs, layout diffs, drift scoring |
59+
| |
60+
| Replay Engine: |
61+
| - Deterministic reproduction of any run |
62+
+-----------------------------------------------------------------------------------------------------------------+
63+
|
64+
v
65+
+-----------------------------------------------------------------------------------------------------------------+
66+
| 8-NODE DETERMINISTIC LOOP (HEART OF THE SYSTEM) |
67+
| |
68+
| [1] PERCEIVE → capture screenshot + XML + hash |
69+
| [2] ENUMERATE → extract actionable elements |
70+
| [3] CHOOSE → strategy/AI/coverage-guided decision |
71+
| [4] ACT → execute via Appium/ADB/Cloud Device |
72+
| [5] VERIFY → confirm visual or structural change |
73+
| [6] PERSIST → upsert screen/action + edges in graph |
74+
| [7] DETECT PROGRESS → stall/forward/loop |
75+
| [8] SHOULD CONTINUE → continue / restart app / switch policy / stop |
76+
| |
77+
| Single writer: run_events |
78+
+-----------------------------------------------------------------------------------------------------------------+
79+
|
80+
v
81+
+-----------------------------------------------------------------------------------------------------------------+
82+
| RUNTIME CORE |
83+
| - Event log (run_events) |
84+
| - Outbox (strict publish ordering) |
85+
| - Graph projector (screens/actions/edges) |
86+
| - Deterministic replay core |
87+
+-----------------------------------------------------------------------------------------------------------------+
88+
89+
190
# ScreenGraph Agent System (MVP Scaffolding)
291

392
## Service Role

0 commit comments

Comments
 (0)