From 0099d128cf23d2c16e27a49aefb63681ade4699f Mon Sep 17 00:00:00 2001 From: Mohammad Saddam Hossain Date: Tue, 14 Jul 2026 09:24:09 +0530 Subject: [PATCH] docs(why): add "Why Selenium Boot / not plain Selenium / not Playwright" pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #5 Three top-of-funnel philosophy pages under docs/why/, adapted from the intro Design Philosophy and README: - Why Selenium Boot? — layered philosophy + outcome-led "what you get" table - Why not plain Selenium? — the boilerplate-you-own argument, without hiding Selenium; incremental adoption - Why not Playwright? — honest, does NOT claim to replace Playwright; cross-links to the Coming-from-Playwright bridge page New "Why Selenium Boot" sidebar category placed right after the intro. Pages cross-link to guides and migration pages instead of duplicating content (keeps SEO authority consolidated). SEO description frontmatter on all three. Build passes. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs-site/docs/why/why-not-plain-selenium.md | 62 ++++++++++++++++++++ docs-site/docs/why/why-not-playwright.md | 59 +++++++++++++++++++ docs-site/docs/why/why-selenium-boot.md | 61 +++++++++++++++++++ docs-site/sidebars.js | 9 +++ 4 files changed, 191 insertions(+) create mode 100644 docs-site/docs/why/why-not-plain-selenium.md create mode 100644 docs-site/docs/why/why-not-playwright.md create mode 100644 docs-site/docs/why/why-selenium-boot.md diff --git a/docs-site/docs/why/why-not-plain-selenium.md b/docs-site/docs/why/why-not-plain-selenium.md new file mode 100644 index 0000000..5cb9282 --- /dev/null +++ b/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` 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` | 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 diff --git a/docs-site/docs/why/why-not-playwright.md b/docs-site/docs/why/why-not-playwright.md new file mode 100644 index 0000000..c8b6ec8 --- /dev/null +++ b/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 diff --git a/docs-site/docs/why/why-selenium-boot.md b/docs-site/docs/why/why-selenium-boot.md new file mode 100644 index 0000000..338b2da --- /dev/null +++ b/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` diff --git a/docs-site/sidebars.js b/docs-site/sidebars.js index d554962..177169c 100644 --- a/docs-site/sidebars.js +++ b/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',