Chrome Remote Control

Control your local Chrome browser from a remote server (AWS EC2) via SSH tunnel.
Browser stays visible on your screen while remote commands execute on it.

Quick Start

# 1. Setup (starts listener + Chrome)
.\helpers\setup.ps1

# 2. Open SSH tunnel (separate terminal)
.\helpers\start-tunnel.ps1

# 3. Run test from remote
.\helpers\run.ps1

How It Works

Local Machine                    SSH Tunnel              Remote Server
┌──────────────┐                ┌──────────┐            ┌──────────────┐
│ Chrome :9225 │◄──CDP──────────┼──:9225───┼────────────┤  Playwright  │
│              │                │          │            │  (node)      │
│ Listener:9223│◄──HTTP─────────┼──:9223───┼────────────┤  commands    │
└──────────────┘                └──────────┘            └──────────────┘

Project Structure

├── src/
│   ├── chrome.js       # Main API (75 functions)
│   ├── listener.js     # HTTP API server
│   ├── config.js       # Config loader
│   └── config.json     # Configuration (ports, SSH)
├── helpers/
│   ├── setup.ps1       # One-command setup
│   ├── start-tunnel.ps1# Start SSH tunnel
│   ├── run.ps1         # Run test on remote
│   └── config-reader.ps1
├── tests/
│   └── test-stability.js  # 75-function test
├── agent/              # Remote agent
├── vscode-extension/   # VS Code extension
└── package.json

API Reference

const chrome = require('./src/chrome.js');

// Navigation
await chrome.open('https://example.com');
await chrome.back();
await chrome.forward();
await chrome.refresh();

// Interaction
await chrome.click('Sign In');
await chrome.clickSelector('#login-btn');
await chrome.clickAt(100, 200);
await chrome.hover('Menu');
await chrome.hoverSelector('.dropdown');
await chrome.fill('input[name="email"]', '[email protected]');
await chrome.type('hello world');
await chrome.press('Enter');
await chrome.clear('input[name="q"]');
await chrome.check('input[type="checkbox"]');
await chrome.uncheck('input[type="checkbox"]');
await chrome.selectOption('select', 'option-value');
await chrome.submitForm('form');
await chrome.drag(100, 100, 300, 300);

// Scrolling
await chrome.scroll(5);
await chrome.scrollTop();
await chrome.scrollBottom();

// Information
await chrome.getTitle();
await chrome.getUrl();
await chrome.getText('body');
await chrome.getText('h1');
await chrome.getLinks();
await chrome.getElements('a');
await chrome.getElementInfo('.card');
await chrome.countElements('img');

// Screenshots
await chrome.screenshot('page.png');
await chrome.screenshotFull('full.png');
await chrome.screenshotElement('h1', 'heading.png');

// Window
await chrome.resize(1280, 720);
await chrome.zoom(1.5);
await chrome.focus();

// Tabs
await chrome.newTab('https://example.com');
await chrome.listTabs();

// Waiting
await chrome.wait(1000);
await chrome.waitForElement('.loaded', 10000);
await chrome.waitForText('Welcome', 10000);
await chrome.waitForNavigation(10000);
await chrome.waitForLoad();

// JavaScript
await chrome.eval('document.title');
await chrome.eval('document.querySelectorAll("a").length');

// Debugging
await chrome.getConsole(5);
await chrome.getDOM('body');
await chrome.getDOMTree(3);
await chrome.getNetwork(5);
await chrome.getPerformance();
await chrome.getResourceTiming();
await chrome.getSEO();
await chrome.getAccessibility();
await chrome.getErrors(5);
await chrome.getCookies();
await chrome.getStorage();

// Assertions
await chrome.assertExists('h1');
await chrome.assertText('Welcome');
await chrome.assertTitle('Home Page');
await chrome.assertUrl('example.com');
await chrome.assertVisible('.banner');
await chrome.assertEnabled('button');
await chrome.assertCount('li', 5);

// Media
await chrome.play();
await chrome.pause();

// Responsive
await chrome.testResponsive('https://example.com');

// System
await chrome.status();
await chrome.stop();

Configuration

Edit src/config.json:

{
  "cdpPort": 9225,
  "listenerPort": 9223,
  "ssh": {
    "host": "aws-controller",
    "user": "ubuntu",
    "keyPath": "~/.ssh/key.pem"
  }
}

Requirements

• Node.js 18+
• Google Chrome
• Playwright (npm install playwright)
• SSH access to remote server

Install

npm install

License

MIT