support of remote browser. Lamdatest, BrowserStack, browserbase, anch…

…orbrowser. Added helper scripts to populate CDP_URL and proper documentation

README.md

@@ -252,6 +252,36 @@ docker run --env-file=.env \
 - If you want Hercules to connect to a visible web browser, try the CDP URL option in the environment file. This option can help you connect Hercules running in your infrastructure to a remote browser like BrowserBase or your self-hosted grid.
 - Use `CDP_ENDPOINT_URL` to set the CDP URL of the Chrome instance that has to be connected to the agent.
 
+### Docker and Remote Browser Support
+
+When running Hercules in Docker, you can connect to remote browser instances using various platforms:
+
+1. **BrowserStack Integration**:
+```bash
+export BROWSERSTACK_USERNAME=your_username
+export BROWSERSTACK_ACCESS_KEY=your_access_key
+export CDP_ENDPOINT_URL=$(python helper_scripts/browser_stack_generate_cdp_url.py)
+```
+
+2. **LambdaTest Integration**:
+```bash
+export LAMBDATEST_USERNAME=your_username
+export LAMBDATEST_ACCESS_KEY=your_access_key
+export CDP_ENDPOINT_URL=$(python helper_scripts/lambda_test_generate_cdp_url.py)
+```
+
+3. **BrowserBase Integration**:
+```bash
+export CDP_ENDPOINT_URL=wss://connect.browserbase.com?apiKey=your_api_key
+```
+
+4. **AnchorBrowser Integration**:
+```bash
+export CDP_ENDPOINT_URL=wss://connect.anchorbrowser.io?apiKey=your_api_key
+```
+
+Note: Video recording is only supported on platforms that use connect_over_cdp (BrowserBase, AnchorBrowser). Platforms using the connect API (BrowserStack, LambdaTest) do not support video recording.
+
 #### Output and Logs
 
 After the command completion:

docs/run_guide.md

@@ -220,6 +220,67 @@ CDP_ENDPOINT_URL=ws://your-chrome-host:9222
 
 This allows Hercules running in Docker to connect to an external browser instance, enabling visible test execution even when running in a container.
 
+## Remote Browser Testing Platforms
+
+Hercules supports running tests on various remote browser platforms using the CDP (Chrome DevTools Protocol) endpoint URL. Here's how to configure different providers:
+
+### BrowserStack
+
+1. Set up your credentials:
+```bash
+export BROWSERSTACK_USERNAME=your_username
+export BROWSERSTACK_ACCESS_KEY=your_access_key
+```
+
+2. Generate CDP URL:
+```bash
+export CDP_ENDPOINT_URL=$(python helper_scripts/browser_stack_generate_cdp_url.py)
+```
+
+Note: Video recording is not supported with BrowserStack as it uses the connect API.
+
+### LambdaTest
+
+1. Set up your credentials:
+```bash
+export LAMBDATEST_USERNAME=your_username
+export LAMBDATEST_ACCESS_KEY=your_access_key
+```
+
+2. Generate CDP URL:
+```bash
+export CDP_ENDPOINT_URL=$(python helper_scripts/lambda_test_generate_cdp_url.py)
+```
+
+Note: Video recording is not supported with LambdaTest as it uses the connect API.
+
+### BrowserBase
+
+1. Set the CDP URL directly:
+```bash
+export CDP_ENDPOINT_URL=wss://connect.browserbase.com?apiKey=your_api_key
+```
+
+BrowserBase supports connect_over_cdp, so video recording will work on the test execution host.
+
+### AnchorBrowser
+
+1. Set the CDP URL directly:
+```bash
+export CDP_ENDPOINT_URL=wss://connect.anchorbrowser.io?apiKey=your_api_key
+```
+
+AnchorBrowser supports connect_over_cdp, so video recording will work on the test execution host.
+
+### Important Notes About Remote Browser Testing
+
+- When using CDP_ENDPOINT_URL, Hercules will connect to the remote browser instance instead of launching a local browser.
+- Video recording capabilities depend on the platform:
+  - Platforms using Playwright's connect API (BrowserStack, LambdaTest) do not support video recording
+  - Platforms using connect_over_cdp (BrowserBase, AnchorBrowser) support video recording on the test execution host
+- Each platform may have different capabilities and configurations available through their respective helper scripts
+- Remote browser testing is particularly useful when running tests in Docker containers or CI/CD pipelines
+
 ## Viewing Results
 
 After test execution, results can be found in several locations:

helper_scripts/browser_stack_generate_cdp_url.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+import os
+import json
+import urllib.parse
+import subprocess
+
+# Use environment variables if set, else fallback to default strings
+BROWSERSTACK_USERNAME = os.environ.get('BROWSERSTACK_USERNAME', 'BROWSERSTACK_USERNAME')
+BROWSERSTACK_ACCESS_KEY = os.environ.get('BROWSERSTACK_ACCESS_KEY', 'BROWSERSTACK_ACCESS_KEY')
+
+desired_cap = {
+    'os': 'osx',
+    'os_version': 'catalina',
+    'browser': 'chrome',  # allowed browsers: chrome, edge, playwright-chromium, playwright-firefox, playwright-webkit
+    'browser_version': 'latest',  # valid only for `chrome` and `edge`
+    'browserstack.username': BROWSERSTACK_USERNAME,
+    'browserstack.accessKey': BROWSERSTACK_ACCESS_KEY,
+    # 'browserstack.geoLocation': 'FR',
+    'project': 'My First Project',
+    'build': 'playwright-python-1',
+    'name': 'My First Test',
+    'buildTag': 'reg',
+    'resolution': '1280x1024',
+    'browserstack.local': 'false',
+    'browserstack.localIdentifier': 'local_connection_name',
+    'browserstack.playwrightVersion': '1.latest',
+    'client.playwrightVersion': '1.latest',  # We will overwrite this with the installed version
+    'browserstack.debug': 'true',
+    'browserstack.console': 'info',
+    'browserstack.networkLogs': 'true',
+    'browserstack.interactiveDebugging': 'true'
+}
+
+def create_cdp_url() -> str:
+    # Dynamically get the local Playwright version
+    playwright_version = subprocess.getoutput('playwright --version').strip().split()[1]
+    desired_cap['client.playwrightVersion'] = playwright_version
+    # import ipdb; ipdb.set_trace()
+    # Construct the final CDP URL
+    raw_caps = json.dumps(desired_cap)
+    encoded_caps = urllib.parse.quote(raw_caps)
+    cdp_url = f"wss://cdp.browserstack.com/playwright?caps={encoded_caps}"
+    return cdp_url
+
+if __name__ == "__main__":
+    print(create_cdp_url())

helper_scripts/lambda_test_generate_cdp_url.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+
+import os
+import json
+import urllib.parse
+import subprocess
+
+# Read from environment variables or use default
+LT_USERNAME = os.environ.get('LAMBDATEST_USERNAME', 'LAMBDATEST_USERNAME')
+LT_ACCESS_KEY = os.environ.get('LAMBDATEST_ACCESS_KEY', 'LAMBDATEST_ACCESS_KEY')
+
+capabilities = {
+    'browserName': 'Chrome',  # Browsers allowed: Chrome, MicrosoftEdge, pw-chromium, pw-firefox, pw-webkit
+    'browserVersion': 'latest',
+    'LT:Options': {
+        'platform': 'Windows 11',
+        'build': 'Playwright Python Build',
+        'name': 'Playwright Test',
+        'user': LT_USERNAME,
+        'accessKey': LT_ACCESS_KEY,
+        'network': True,
+        'video': True,
+        'console': True,
+        'tunnel': False,  # set to True if testing locally hosted pages
+        # 'tunnelName': '',
+        # 'geoLocation': '',  # e.g. 'US', 'FR', 'IN'
+        'playwrightClientVersion': '1.latest'  # Will be updated dynamically
+    }
+}
+
+def create_lt_cdp_url() -> str:
+    # Dynamically get the local Playwright version
+    playwright_version = subprocess.getoutput('playwright --version').strip().split()[1]
+    # Update the capabilities to reflect the local Playwright version
+    capabilities['LT:Options']['playwrightClientVersion'] = playwright_version
+
+    # Construct the final CDP URL for LambdaTest
+    raw_caps = json.dumps(capabilities)
+    encoded_caps = urllib.parse.quote(raw_caps)
+    lt_cdp_url = f"wss://cdp.lambdatest.com/playwright?capabilities={encoded_caps}"
+    return lt_cdp_url
+
+if __name__ == "__main__":
+    print(create_lt_cdp_url())