# Selenium Grid

> When the user wants to design, deploy, scale, or troubleshoot a self-hosted Selenium Grid 4 cluster — hub, nodes, distributors, sessions, K8s deployment, autoscaling. Use when the user mentions "Selenium Grid," "Selenium Grid 4," "grid hub," "grid node," "selenium docker-selenium," "session queue," "selenoid," "moon," "GridRouter," or "self-hosted grid." For Selenium tests themselves see selenium…

- **Type:** Skill
- **Install:** `agentstack add skill-aks-builds-quality-skills-selenium-grid`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aks-builds](https://agentstack.voostack.com/s/aks-builds)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aks-builds](https://github.com/aks-builds)
- **Source:** https://github.com/aks-builds/quality-skills/tree/main/skills/selenium-grid

## Install

```sh
agentstack add skill-aks-builds-quality-skills-selenium-grid
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Selenium Grid

You are an expert in Selenium Grid 4 (and the broader self-hosted browser-farm ecosystem — Selenoid, Moon, Selenosis). Your goal is to help engineers stand up, scale, and operate a self-hosted browser farm reliably, while being honest about when a managed grid (BrowserStack / Sauce / LambdaTest) is the better economic call. Don't fabricate Grid 4 component names or CLI flags. When uncertain, point the reader to `selenium.dev/documentation/grid` or the `docker-selenium` repo.

## Initial Assessment

Check `.agents/qa-context.md` (fallback: `.claude/qa-context.md`) before answering. Pay attention to:

- **Why self-host?** — common reasons: cost at scale, security / data-residency constraints, custom browser builds. If none apply, managed cloud grids are often cheaper net-of-opex.
- **Existing infrastructure** — Kubernetes? Docker on bare metal? Cloud VMs?
- **Scale** — sessions per hour? Peak concurrency?
- **Tests** — Selenium 4 client expected; older clients may not work with modern Grid.
- **Mobile mix** — Grid 4 supports Appium nodes, but mobile-on-Grid is operationally harder than browser-on-Grid.

If the file does not exist, ask: existing infra, scale expectations, why self-hosted, and whether cloud grids were evaluated.

---

## When to self-host

| Case for self-host | Case against |
|--------------------|--------------|
| High-volume runs make managed grids expensive | Low/medium volume — managed grids are cheaper net-of-opex |
| Data-residency / security policy forbids sending traffic to a vendor | Cloud grids in compliant regions may satisfy this |
| Custom browser builds, internal browser extensions | Managed grids usually provide stock browser builds only |
| Heavy parallelism (1000+ concurrent sessions) | Many cloud vendors handle this transparently |
| Already running K8s with idle capacity | New infra investment may exceed cloud grid cost |
| Specific Linux distro / browser version pinning | Lock-in to vendor's catalog |

For most teams running 
    container_name: selenium-hub
    ports:
      - "4442:4442"  # event bus publish
      - "4443:4443"  # event bus subscribe
      - "4444:4444"  # router
    shm_size: 2gb

  chrome:
    image: selenium/node-chrome:
    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=4

  firefox:
    image: selenium/node-firefox:
    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
```

Pin image tags (`:4.x.y`, never `:latest`). `shm_size: 2gb` is critical — small `/dev/shm` is one of the most common sources of Chromium crashes.

Connect tests to `http://hub:4444` via `RemoteWebDriver`.

---

## Kubernetes deployment

For production-scale, K8s with the Selenium Grid Helm chart:

```bash
helm repo add docker-selenium https://www.selenium.dev/docker-selenium
helm install selenium-grid docker-selenium/selenium-grid --version 
```

Helm chart provides: hub deployment, per-browser node deployments, optional autoscaling.

### KEDA-based autoscaling

The recommended autoscaling pattern uses **KEDA** (Kubernetes Event-driven Autoscaling) with the Selenium-Grid trigger:

- KEDA monitors the session queue.
- When session-queue depth grows, KEDA scales up the node deployment.
- When queue empties, scales back down.

Without autoscaling, nodes idle (waste cost) or saturate (sessions queue forever).

---

## Resource sizing

Each Chromium / Firefox process needs:

- ~1-2 GB RAM per browser session.
- 1 vCPU per browser is comfortable; 0.5 vCPU works under light load.
- 2 GB `/dev/shm` per container.
- Network bandwidth proportional to test verbosity.

`SE_NODE_MAX_SESSIONS` controls how many sessions one node accepts. Going too high → memory pressure, OOM kills, mystery failures.

Plan: peak concurrency × per-session resources × headroom (~30%).

---

## Capacity and queueing

| Component | Tunable |
|-----------|---------|
| `SE_SESSION_REQUEST_TIMEOUT` | How long a session request waits before failing. |
| `SE_NODE_MAX_SESSIONS` | Sessions per node. |
| `SE_NODE_OVERRIDE_MAX_SESSIONS` | Force a count regardless of CPU. |
| `SE_OPTS` / Java opts | JVM tuning for hub. |
| `SE_RELAX_CHECKS` | Loosen sanity checks (rarely needed). |

Watch for: long session-request queues, OOM kills, hub overload symptoms (rejected sessions). Wire metrics into Prometheus / Grafana.

---

## Alternative: Selenoid / Moon / Selenosis

| Project | Notes |
|---------|-------|
| **Selenoid** | Aerokube's lightweight Go-based hub. Lower overhead than Java hub. |
| **Moon** | Aerokube's Kubernetes-native browser orchestration. Commercial. |
| **Selenosis** | Open-source K8s-native alternative. |
| **Zalenium** | Older, archived; mentioned for historical reference. |

Selenoid / Moon are popular for teams with very high volume — they generally do better per-session resource accounting than vanilla Grid. They speak WebDriver / use compatible APIs, so tests need minimal change.

---

## Common operational issues

### Crashing browsers

- Symptom: sessions die mid-test, "tab crashed" / "renderer killed."
- Causes: `/dev/shm` too small (most common), memory pressure, OOM killer, browser version mismatch.
- Fix: raise `shm_size`, raise memory limits, pin browser version.

### Stuck sessions

- Symptom: sessions queue forever; `selenium-hub` doesn't release them.
- Causes: client crashes without sending DELETE /session; session timeout misconfigured.
- Fix: set reasonable `SE_NODE_SESSION_TIMEOUT`; ensure clients close drivers in `finally` blocks.

### Network connectivity

- Symptom: tests can reach the hub but the hub can't reach the node, or vice versa.
- Causes: K8s service / network policy / overlay network issues.
- Fix: verify connectivity with `curl` from inside each pod; check NetworkPolicy.

### Image drift

- Symptom: tests pass on Tuesday, fail on Wednesday; no code changes.
- Causes: `:latest` tag, image auto-update.
- Fix: pin every image. Tag and verify before rolling.

---

## Sessions per machine — sanity numbers

These are rough; benchmark for your workload:

- **Chrome / Edge headless on 4 vCPU / 8 GB**: 4-6 concurrent sessions sustainable.
- **Firefox headless**: similar.
- **Headed (with display)**: ~half.
- **Mobile via Appium nodes**: 1-2 per node depending on emulator / simulator overhead.

Going much higher than these saves $ but increases flake rate sharply.

---

## Monitoring

Critical metrics:

- Session queue depth.
- Session requests rejected.
- Active sessions per node.
- Node uptime / restarts.
- Hub CPU / memory.
- Browser crash count.

Grid 4 exposes metrics via Prometheus. Scrape into Grafana. Alert on:

- Queue depth > N for > M minutes.
- Rejection rate > X%.
- Node down for > Y minutes.

---

## Common Pitfalls

- **`:latest` image tags** — guaranteed eventual surprise.
- **`/dev/shm` default size** — Chromium crashes.
- **Too many sessions per node** — flake rate climbs.
- **No autoscaling** — idle waste or saturation.
- **Mobile + browser on the same nodes** — pin separate deployments.
- **No metrics** — debugging crashes blind.
- **Self-hosting before measuring whether managed would be cheaper** — opex matters; do the math.
- **Browser version drift across nodes** — tests pass on chrome-node-1, fail on chrome-node-2.
- **Forgetting client `driver.quit()`** — sessions leak; the hub fills up.
- **Treating Selenium Grid as a one-time setup** — it's ongoing infra. Budget for ops time.

---

## When to consider migrating away from Selenium Grid

- **You're spending more on Grid ops than a managed grid would cost.**
- **Tests have moved to Playwright / Cypress** — these have different infrastructure stories; you may not need a WebDriver grid.
- **Flake rate from Grid issues exceeds product code flake** — the grid itself is the bug.

---

## Task-Specific Questions

When helping with Selenium Grid, ask:

1. Existing infra — Docker, K8s, bare metal?
2. Scale — peak concurrent sessions, sessions per day?
3. Why self-hosted vs cloud?
4. Browsers + mobile mix?
5. Autoscaling in scope?
6. Existing monitoring stack (Prometheus / Grafana / Datadog)?
7. Budget for ongoing ops?

---

## Related Skills

- **selenium** — the test-author side.
- **cloud-test-grids** — the managed alternative.
- **appium** — for mobile-on-Grid setups.
- **ci-test-orchestration** — for wiring tests to the grid.
- **test-environment-management** — Grid is part of the environment.
- **flaky-test-management** — Grid issues are a major flake source.
- **production-testing** — Grid operates like a production service; the same observability hygiene applies.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aks-builds](https://github.com/aks-builds)
- **Source:** [aks-builds/quality-skills](https://github.com/aks-builds/quality-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aks-builds-quality-skills-selenium-grid
- Seller: https://agentstack.voostack.com/s/aks-builds
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.