docs(why): add "Why Selenium Boot / not plain Selenium / not Playwright" pages

docs-site/docs/why/why-not-plain-selenium.md

@@ -0,0 +1,62 @@
+---
+description: "Why not plain Selenium? Raw Selenium is low-level by design — every team rebuilds the same driver factory, wait utils, retry analyzer, and reporting. Selenium Boot is that framework, maintained and tested, without hiding Selenium."
+id: why-not-plain-selenium
+title: Why not plain Selenium?
+sidebar_label: Why not plain Selenium?
+sidebar_position: 2
+---
+
+# Why not plain Selenium?
+
+Nothing is wrong with Selenium — Selenium Boot is **built on it** and never hides it. The question isn't "Selenium or not?" It's: *who writes and maintains the scaffolding Selenium deliberately leaves out?*
+
+Raw Selenium hands you a `WebDriver` and stops there. Turning that into a real test suite means building — and then owning forever — the same set of pieces every team rebuilds.
+
+---
+
+## The boilerplate you own with plain Selenium
+
+Almost every Java Selenium project grows its own copy of this:
+
+- A **`DriverFactory`** with `ThreadLocal<WebDriver>` juggling for parallel runs
+- Driver-binary management (historically WebDriverManager)
+- A **`WaitUtils`** wrapper around `WebDriverWait` / `ExpectedConditions`, imported everywhere
+- An **`IRetryAnalyzer`** plus a listener to attach it, for flaky tests
+- A screenshot-on-failure **`ITestListener`**
+- Reporting wiring (ExtentReports / Allure) and CI glue
+
+It's unpaid infrastructure: you write it, debug it, and maintain it — and it's rarely tested or parallel-safe. It gets **rewritten from scratch at every new project or company.**
+
+---
+
+## What Selenium Boot changes
+
+Selenium Boot **is** that framework — already built, maintained, tested, thread-safe, and documented. You keep the part that's actually yours (test intent) and delete the plumbing:
+
+| Plain Selenium (you build & maintain) | Selenium Boot |
+|---|---|
+| `DriverFactory` + `ThreadLocal<WebDriver>` | Extend `BaseTest` — lifecycle managed, parallel-safe |
+| WebDriverManager / driver binaries | Selenium Manager, automatic |
+| `WaitUtils` / `WebDriverWait` helpers | Auto-waiting locators + [`WaitEngine`](/docs/guides/wait-engine) |
+| Brittle CSS/XPath selectors | [Accessibility-first locators](/docs/guides/semantic-locators) |
+| `IRetryAnalyzer` + listener | [`@Retryable`](/docs/guides/retry) + one config line |
+| Screenshot-on-failure listener | Automatic on failure |
+| ExtentReports/Allure wiring | [HTML report](/docs/reporting/html-report) + JUnit XML included |
+| Bespoke CI wiring per project | Auto-detects GitHub Actions / Jenkins / CircleCI |
+| You fix the bugs | The framework ships the fixes |
+
+---
+
+## …without hiding Selenium
+
+The catch with most "productivity layers" is that they take `WebDriver` away and trap you when the abstraction leaks. Selenium Boot doesn't. When the conventions don't fit, `getDriver()` hands you the raw `WebDriver` and you drop straight to `By` / `WebElement`. Opinionated defaults, full escape hatch.
+
+Because it *is* Selenium, adoption is incremental — you can point a single test class at `BaseTest` and a half-migrated suite still runs.
+
+---
+
+## Next steps
+
+- [Migrate from Selenium + TestNG](/docs/migration/from-selenium-testng) — the side-by-side "delete the plumbing" guide
+- [Why Selenium Boot?](/docs/why/why-selenium-boot) — the overall philosophy
+- [Getting Started](/docs/getting-started) — first test in 5 minutes

docs-site/docs/why/why-not-playwright.md

@@ -0,0 +1,59 @@
+---
+description: "Why not Playwright? An honest answer: Selenium Boot does not replace Playwright. It brings Playwright's best ideas — accessibility-first locators, auto-waiting, web-first assertions — to teams staying in the Selenium / Java / Grid ecosystem."
+id: why-not-playwright
+title: Why not Playwright?
+sidebar_label: Why not Playwright?
+sidebar_position: 3
+---
+
+# Why not Playwright?
+
+Let's be honest up front: **Selenium Boot does not replace Playwright.** Playwright is an excellent tool with a genuinely different architecture, and if you're greenfield with no Selenium investment, it's a great choice.
+
+So "Why not Playwright?" isn't a takedown — it's a question with a real answer for a specific audience: **teams already in the Selenium / Java / JVM world** who admire Playwright's ergonomics but don't want to abandon their stack, their Selenium Grid, or their team's skills to get them.
+
+---
+
+## The ergonomics you don't have to give up
+
+You don't have to leave Selenium to get the things people love about Playwright. Selenium Boot brings those ideas into the Selenium ecosystem:
+
+| Playwright idea | In Selenium Boot |
+|---|---|
+| Accessibility-first locators | [`getByRole` / `getByLabel` / `getByText`](/docs/guides/semantic-locators) — target the accessibility tree, survive CSS/DOM refactors |
+| Auto-waiting | Auto-waiting actions + [`WaitEngine`](/docs/guides/wait-engine) — `Thread.sleep()` disappears |
+| Web-first assertions | `assertThat(...)` that auto-retries until true |
+| Convention over configuration | Zero-boilerplate defaults, optional `selenium-boot.yml` |
+
+…all while keeping your existing **Selenium / Java / TestNG** stack and **Selenium Grid**, and without ever hiding raw Selenium.
+
+---
+
+## Where Playwright is genuinely different
+
+Honesty cuts both ways. These are real architectural differences, not marketing:
+
+- **Architecture** — Playwright drives browsers over its own protocol with fast, isolated browser contexts and built-in tracing. Selenium Boot is built on **Selenium WebDriver / the W3C protocol** — you get the whole Selenium ecosystem, but WebDriver's model, not Playwright's.
+- **Language & runtime** — Playwright is multi-language and ships its own managed browser builds. Selenium Boot is **JVM-only** and runs your normally installed browsers.
+- **Scaling** — Playwright has its own worker/sharding model; Selenium Boot uses **Selenium Grid** and TestNG parallelism, slotting into infrastructure you may already run.
+
+For the full familiar-vs-different breakdown, see the bridge page: [Coming from Playwright](/docs/migration/coming-from-playwright).
+
+---
+
+## Choosing honestly
+
+| Choose… | If… |
+|---|---|
+| **Playwright** | Greenfield, no Selenium investment, want its context model / tracing, team happy in Node/Python. |
+| **Selenium Boot** | You're on **Selenium / Java / TestNG**, run (or want) **Selenium Grid**, and want Playwright-style ergonomics without leaving that stack. |
+
+Both are legitimate. Selenium Boot exists so that "we're a Selenium shop" no longer means giving up accessibility-first locators, auto-waiting, and web-first assertions.
+
+---
+
+## Next steps
+
+- [Coming from Playwright](/docs/migration/coming-from-playwright) — the full bridge page
+- [Accessibility-First Locators](/docs/guides/semantic-locators) — the `getByRole`/`getByLabel` family
+- [Why Selenium Boot?](/docs/why/why-selenium-boot) — the overall philosophy

docs-site/docs/why/why-selenium-boot.md

@@ -0,0 +1,61 @@
+---
+description: "Why Selenium Boot: the Spring Boot of Selenium — zero setup, Playwright-inspired locators and auto-waiting, and enterprise features, without hiding Selenium. The philosophy before the API."
+id: why-selenium-boot
+title: Why Selenium Boot?
+sidebar_label: Why Selenium Boot?
+sidebar_position: 1
+---
+
+# Why Selenium Boot?
+
+Developers adopt a philosophy before they adopt an API. This page is the philosophy.
+
+> Selenium Boot is the Spring Boot of Selenium — zero setup, smarter defaults, Playwright-inspired APIs, and enterprise features, without hiding Selenium.
+
+Selenium is powerful and everywhere, but it's deliberately low-level: it gives you a `WebDriver` and gets out of the way. Everything else — driver lifecycle, waits, retries, reporting, CI wiring — is left to you. Every team ends up rebuilding the same scaffolding. Selenium Boot **is** that scaffolding, done once, properly.
+
+---
+
+## The idea in three layers
+
+Selenium Boot is opinionated, but not a cage. The design is layered, not equal parts:
+
+1. **Opinionated core (primary).** Convention over configuration, zero boilerplate by default. Add one dependency, extend `BaseTest` / `BasePage`, and the framework has already made the sensible decisions — driver lifecycle, waits, retries, reporting, CI wiring. `selenium-boot.yml` is optional; sensible defaults cover you if you never write it.
+2. **Never hides Selenium (the constraint).** Unlike heavier abstractions, Selenium Boot never takes the raw `WebDriver` away from you. When the conventions don't fit, drop straight to `WebDriver` / `By` / `WebElement`. Opinionated without being a cage.
+3. **Extensible toolkit (the escape hatch).** An SPI/registry plugin system makes it modular for power users — custom drivers, report adapters, lifecycle hooks. Most users never touch it.
+
+---
+
+## What you get for one dependency
+
+Outcomes first — with the API that delivers them:
+
+| Outcome | How |
+|---|---|
+| **Never write `Thread.sleep()` again** | Auto-waiting locators + [`WaitEngine`](/docs/guides/wait-engine) |
+| **Tests survive CSS refactors** | [Accessibility-first locators](/docs/guides/semantic-locators) — `getByRole`, `getByLabel`, `getByText` |
+| **Flaky tests recover automatically** | [`@Retryable`](/docs/guides/retry) + one config line — no `IRetryAnalyzer` wiring |
+| **See exactly why a test failed** | Screenshot auto-captured on failure, embedded in the [HTML report](/docs/reporting/html-report) |
+| **No WebDriver binaries to manage** | Selenium Manager resolves drivers automatically |
+| **Parallel-safe out of the box** | ThreadLocal driver isolation — [parallel execution](/docs/guides/parallel) |
+| **Extend it without forking it** | Java SPI plugins for drivers, reports, hooks |
+
+---
+
+## Who it's for
+
+- **Teams already invested in Selenium** who want Playwright-style ergonomics without leaving the Selenium / Java / TestNG stack, their team's skills, or Selenium Grid.
+- **Teams maintaining a home-grown framework** — a `BaseTest`, a `DriverFactory`, a pile of wait utilities — who'd rather delete that plumbing than keep debugging it.
+
+The two "why" questions those teams actually ask each have their own page:
+
+- [Why not plain Selenium?](/docs/why/why-not-plain-selenium) — what the boilerplate really costs
+- [Why not Playwright?](/docs/why/why-not-playwright) — an honest comparison (we don't claim to replace it)
+
+---
+
+## Next steps
+
+- [Getting Started](/docs/getting-started) — first test in 5 minutes
+- [BaseTest](/docs/guides/base-test) / [BasePage](/docs/guides/base-page) — the base classes you extend
+- [Configuration Reference](/docs/configuration) — the full `selenium-boot.yml`

docs-site/sidebars.js

@@ -2,6 +2,15 @@
 const sidebars = {
   docsSidebar: [
     'intro',
+    {
+      type: 'category',
+      label: 'Why Selenium Boot',
+      items: [
+        'why/why-selenium-boot',
+        'why/why-not-plain-selenium',
+        'why/why-not-playwright',
+      ],
+    },
     'getting-started',
     'gradle',
     'configuration',