From c41506a6ec4c695952909f28bb88e0f4fdc81860 Mon Sep 17 00:00:00 2001
From: Mohammad Saddam Hossain <sddmhossain786@gmail.com>
Date: Thu, 23 Jul 2026 10:26:39 +0530
Subject: [PATCH] docs: gate cloud-execution page on 3.2.1, fix missing config
 keys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cloud execution does not work in any released version. ConfigurationLoader.
validate() rejects any execution.mode other than local/remote (present at
every tag v2.0.0 through v3.2.0), even though the browserstack/saucelabs
providers behind it are fully implemented. A fix ships in 3.2.1 (not yet
released).

- Added a version-gated caution banner at the top of the page stating cloud
  execution requires 3.2.1+. Deliberately does not name any single "broken"
  version (broken in every release containing the feature: 2.6.0, 3.0.0,
  3.1.0, 3.1.1, 3.2.0) and stays accurate with zero follow-up edits once
  3.2.1 ships, since docs.seleniumboot.com is unversioned.

- Fixed all 8 YAML config blocks on the page: each omitted the top-level
  browser: and timeouts: keys that ConfigurationLoader.validate() requires,
  so copy-pasting any of them failed before even reaching the mode check
  ("Browser configuration must be specified"). Same defect class as the
  README (P1-6a) and guides/parallel.md (PR #33) fixes.

Verified against real Maven Central 3.2.0 + ConfigurationLoader: each
corrected block still fails at the mode check under its documented mode
(browserstack/saucelabs) — that's the bug being documented — but loads
clean (exit path "LOADED OK") when the identical file is loaded with
mode: local, proving the added browser/timeouts keys are correct and
complete.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs-site/docs/cloud-execution.md | 62 +++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs-site/docs/cloud-execution.md b/docs-site/docs/cloud-execution.md
index 590f7c7..02d42a0 100644
--- a/docs-site/docs/cloud-execution.md
+++ b/docs-site/docs/cloud-execution.md
@@ -9,6 +9,10 @@ sidebar_position: 12
 
 Selenium Boot supports running your test suite on **BrowserStack** and **Sauce Labs** with zero test-code changes. Switch from local Chrome to a cloud browser farm by changing one line in `selenium-boot.yml`.
 
+:::caution Requires Selenium Boot 3.2.1+
+Cloud execution (`execution.mode: browserstack` or `saucelabs`) requires **Selenium Boot 3.2.1 or later**. It does not work in any earlier release — config loading rejects any `execution.mode` other than `local` or `remote` at startup — regardless of what the examples on this page show.
+:::
+
 ---
 
 ## How it works
@@ -43,8 +47,17 @@ execution:
     osVersion:     "11"
     browser:       chrome
     browserVersion: latest
+
+browser:
+  name: chrome   # required by every selenium-boot.yml, distinct from browserstack.browser above
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
+`browser` and `timeouts` are required top-level blocks for every `selenium-boot.yml` — see the [Configuration Reference](/docs/configuration).
+
 Set environment variables before running:
 
 ```bash
@@ -65,6 +78,13 @@ execution:
     osVersion:    "11"              # 11 | 10 | Sonoma | Ventura | …
     browser:      chrome            # chrome | firefox | edge | safari
     browserVersion: latest          # latest | 120.0 | 119.0 | …
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
 ### Mobile devices
@@ -78,6 +98,13 @@ execution:
     browser:      chrome
     device:       "Samsung Galaxy S23"
     realMobile:   true
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
 ### Raw capability overrides
@@ -98,6 +125,13 @@ execution:
       networkLogs: true
       consoleLogs: verbose
       video: true
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
 ### Session link in HTML report
@@ -125,6 +159,13 @@ execution:
     platformName:  "Windows 11"
     browser:       chrome
     browserVersion: latest
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
 ### Regions
@@ -153,6 +194,13 @@ execution:
       tags: ["regression", "nightly"]
       build: "v2.1.0"
       recordVideo: true
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
 ### Session link in HTML report
@@ -177,6 +225,13 @@ execution:
     osVersion: "11"
     browser:   chrome
     browserVersion: latest
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```
 
 :::info Session limits
@@ -234,4 +289,11 @@ execution:
     browserVersion: latest
     capabilities:                   # raw sauce:options overrides
       recordVideo: true
+
+browser:
+  name: chrome
+
+timeouts:
+  explicit: 10
+  pageLoad: 30
 ```