The Complete Production SOP: How to Deploy and Run Selenium Grid Distributed Node Execution in Autonomous AI Agents
Step-by-step SOP to install and run Selenium Grid Distributed Node Execution in Codex, Claude Code, and Cursor. Includes verified prompts and troubleshooting.
Technical Overview & Architectural Context
Autonomous coding agents frequently stumble when orchestrating distributed browser infrastructure. Without deterministic constraints, models like Claude Code or Codex default to launching unmanaged local WebDriver instances, failing to configure proper remote endpoints or inadvertently hardcoding ephemeral container IDs. This leads to node saturation, leaked browser memory locks, and dangling grid sessions that exhaust test runner concurrency within minutes. Enforcing the Selenium Grid Distributed Node Execution skill establishes strict structural boundaries. It guarantees that any generated automation defines declarative docker-compose topologies, establishes standardized RemoteWebDriver endpoints, injects resilient timeout configurations, and wraps session lifecycles in non-negotiable cleanup blocks. By confining agent generation to deterministic SOPs, testing pipelines scale across Chrome, Firefox, and Edge nodes without infrastructure deadlocks or out-of-memory cascading failures.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent runtime directory.
Agent runtimes such as Claude Code, Cursor, and Codex automatically scan dedicated skill paths (such as ~/.agents/skills or project-level .agents/skills) to ingest runtime procedural rules and YAML triggers. Downloading and mounting the SKILL.md specification ensures the agent detects distributed browser automation capabilities during task planning.
mkdir -p ~/.agents/skills/selenium-grid-test-automation && curl -fsSL https://askills.dev/api/skills/selenium-grid-test-automation/raw -o ~/.agents/skills/selenium-grid-test-automation/SKILL.md---
name: "selenium-grid-test-automation"
description: "Distribute browser automation tasks across a scalable Selenium Grid infrastructure."
metadata:
author: "SeleniumHQ"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "run tests on selenium grid"
- "configure selenium hub and nodes"
- "remote webdriver python"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Selenium Grid Distributed Node Execution
Configures Selenium Grid (Hub and Nodes): executing browser automation across Chrome, Firefox, and Edge nodes, managing remote WebDriver sessions, and handling dynamic grid scaling in Docker.Place the SKILL.md inside your workspace under `.agents/skills/` if you want team-wide enforcement committed directly to source control without bloating user-level global states.
Ensure directory permissions are readable by your user group (0755); otherwise, sandboxed agent daemons running with lowered privileges will silently skip reading SKILL.md.
Environment Secrets & Dependency Validation
Configure grid host routing and test concurrency variables safely without committing credentials to source control.
Remote WebDriver sessions depend on network reachable Hub URLs. Define hub host addresses, default timeouts, and browser concurrent worker pools using environment variables rather than embedding hardcoded addresses into test scripts.
echo 'SELENIUM_HUB_URL=http://localhost:4444/wd/hub\nSELENIUM_PAGE_LOAD_TIMEOUT=30\nSELENIUM_GRID_MAX_INSTANCES=5' >> .env.localReference grid endpoints via standard environment lookups `os.getenv('SELENIUM_HUB_URL', 'http://hub:4444/wd/hub')` to enable transparent toggling between Docker host networks and local localhost bindings.
Verify `.env.local` is present in `.gitignore`. Agent execution checkpoints will fail verification gates if uncommitted environment files containing infrastructure metadata are committed to Git.
Intent Matching & Trigger Invocation
Execute user prompts that activate the deterministic remote WebDriver generation workflow.
When prompted with trigger phrases such as 'configure selenium hub and nodes' or 'remote webdriver python', the agent matches the skill frontmatter and applies the mandatory 4-step SOP: docker-compose orchestration, remote session initialization, try...finally quit lifecycle, and explicit timeouts.
claude 'Generate a distributed Python test suite for our checkout flow using remote webdriver python across chrome and firefox nodes.'import os
from selenium import webdriver
from selenium.webdriver.chrome.options import Options as ChromeOptions
from selenium.webdriver.firefox.options import Options as FirefoxOptions
HUB_URL = os.getenv('SELENIUM_HUB_URL', 'http://localhost:4444/wd/hub')
def run_remote_checkout(browser_name: str):
if browser_name == 'chrome':
options = ChromeOptions()
else:
options = FirefoxOptions()
options.add_argument('--headless')
options.add_argument('--no-sandbox')
options.page_load_strategy = 'eager'
driver = webdriver.Remote(command_executor=HUB_URL, options=options)
driver.set_page_load_timeout(int(os.getenv('SELENIUM_PAGE_LOAD_TIMEOUT', 30)))
try:
driver.get('https://example.com/checkout')
assert 'Checkout' in driver.title
finally:
driver.quit()Explicitly specify target browser matrices (e.g., 'chrome and firefox on selenium grid') in your prompt so the agent initializes heterogeneous Node services inside docker-compose.yml.
Never omit `driver.quit()` inside the `finally` block; simply calling `driver.close()` keeps the RemoteWebDriver session alive in Selenium Hub, blocking subsequent tests from acquiring an execution slot.
Verification, Linting & Output Quality Gate
Validate compose topology, remote driver syntax, and lint configurations before accepting deliverables.
The skill enforces automated self-checks: running flake8 or ruff for Python syntax, validating compose configuration with `docker compose config`, and executing a smoke session to guarantee grid availability.
docker compose -f docker-compose.selenium.yml config && flake8 tests/test_distributed_checkout.pyservices:
selenium-hub:
image: selenium/hub:4.18.1
container_name: selenium-hub
ports:
- "4444:4444"
chrome-node:
image: selenium/node-chrome:4.18.1
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
- SE_EVENT_BUS_PUBLISH_PORT=4442
- SE_EVENT_BUS_SUBSCRIBE_PORT=4443
- SE_NODE_MAX_SESSIONS=2
firefox-node:
image: selenium/node-firefox:4.18.1
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
- SE_EVENT_BUS_PUBLISH_PORT=4442
- SE_EVENT_BUS_SUBSCRIBE_PORT=4443
- SE_NODE_MAX_SESSIONS=2Ensure `shm_size: 2gb` is declared on all browser node containers; modern Chromium engines crash intermittently under high parallel workloads if left on default 64MB /dev/shm.
Inspect the agent git diff prior to execution. Verify that shell command execution permissions remain disabled (`shell_exec: false`) in SKILL.md so the agent cannot inadvertently boot destructive container down commands.
Real-World Scenario: Scale Parallel E-Commerce End-to-End Regression Suite Across Selenium Grid
“We need to run tests on selenium grid. Create a docker-compose.selenium.yml with 1 hub, 2 chrome nodes, and 1 firefox node, then implement a Python regression test using remote webdriver python that executes a search query with explicit page timeouts and releases slots on completion.”
Runtime Troubleshooting & Failure Modes
Root Cause: The Selenium Hub is running, but registered Chrome nodes have exhausted their max concurrent session capacity, or the node failed to register with the Event Bus publish/subscribe ports.
docker compose -f docker-compose.selenium.yml scale chrome-node=3 && curl -s http://localhost:4444/status | jq .value.readyRoot Cause: Browser rendered a heavy script without an explicit page load timeout, or the Node container ran out of shared memory (/dev/shm) causing Chrome tab crash.
driver.set_page_load_timeout(20)
# In docker-compose.selenium.yml:
# services.chrome-node.shm_size: 2gbFrequently Asked Questions (Selenium Grid Distributed Node Execution SOP)
Q:Can I use Selenium Grid Distributed Node Execution across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification supported across all modern agent runtimes. Simply mount it in each tool's configuration directory or at `.agents/skills/selenium-grid-test-automation` in your project root.
Q:How does Selenium Grid Distributed Node Execution prevent context window overflow during long agent sessions?
By establishing concise procedural boundaries and deterministic validation gates rather than polluting system prompts with redundant rules. The agent receives only necessary triggers and execution invariants (e.g., RemoteWebDriver lifecycle, compose architecture), conserving context tokens for project logic.
Q:Does this skill require escalated root or container permissions?
No. It is audited with a security score of 98/100 and runs safely within workspace-scoped sandboxes. The skill requires workspace file read/write access to construct test scripts and compose manifests, while keeping shell execution and network escalation guarded.
Ready to equip your autonomous agent with Selenium Grid Distributed Node Execution?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.