From 8b1041a58eef129c628349c5d07b7c4a11bd1375 Mon Sep 17 00:00:00 2001 From: Mohammad Saddam Hossain Date: Wed, 22 Jul 2026 09:09:10 +0530 Subject: [PATCH] docs: 60-second quickstart up top, and fix two copy-paste blockers The README led with philosophy; the first runnable instruction was ~70 lines down, behind a 7-step walkthrough. Adds a verified 3-file quickstart directly under the title so the first thing a visitor sees is a green test. Two real defects found while writing it, both of which broke copy-paste: - The documented "minimum" selenium-boot.yml omitted the timeouts block. ConfigurationLoader validates timeouts.explicit and timeouts.pageLoad as positive ints (primitives, so absent = 0), and aborts the suite with "Selenium Boot failed to initialize". Verified: the old snippet exits 1. - The pom.xml snippet pinned no maven-compiler-plugin. On Maven <=3.8.x the compiler level falls back to source/target 5 and the build fails with "Source option 5 is no longer supported" on any modern JDK. This is the same defect already fixed in the IntelliJ wizard's ProjectScaffold. Also corrects the claim that selenium-boot.yml is optional (the loader throws if it is missing) in both the README and CLAUDE.md, and repoints the docs link from the stale seleniumboot.github.io URL to docs.seleniumboot.com. Verified end-to-end on Maven 3.8.7 + JDK 25 against Central 3.2.0 and real headless Chrome: 1 test, passed, exit 0. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 2 +- README.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 102 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8806bf8..7389188 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,7 +77,7 @@ All source lives under `src/main/java/com/seleniumboot/`. Key packages: - **Registry + SPI** — `DriverProviderRegistry`, `PluginRegistry`, `ReportAdapterRegistry` use `ServiceLoader` for extensibility. - **ThreadLocal driver isolation** — `DriverManager` stores `WebDriver` per thread; safe for parallel TestNG execution. - **Template Method** — `BaseTest` / `BasePage` define framework-managed lifecycle; users override hook methods. -- **Convention over configuration** — `SeleniumBootDefaults` provides sensible defaults; `selenium-boot.yml` is optional. +- **Convention over configuration** — `SeleniumBootDefaults` supplies fallbacks for optional fields, but `selenium-boot.yml` itself is **required**: `ConfigurationLoader` throws if the file is absent, and validates that `execution.mode`, `browser.name` (or `browser.matrix`), `timeouts.explicit` and `timeouts.pageLoad` are all present and positive. ### Public API Contract diff --git a/README.md b/README.md index e832913..59e85e2 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,89 @@ [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) [![Good first issues](https://img.shields.io/github/issues/seleniumboot/selenium-boot/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/seleniumboot/selenium-boot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) -**[Documentation](https://seleniumboot.github.io/selenium-boot) · [Sample Project](https://github.com/seleniumboot/selenium-boot-test) · [Changelog](#project-status)** +**[Documentation](https://docs.seleniumboot.com) · [Sample Project](https://github.com/seleniumboot/selenium-boot-test) · [Changelog](#project-status)** + +--- + +## Quickstart — a green test in 60 seconds + +Three files. Copy them as-is and `mvn test` goes green against a real Chrome. + +**Prerequisites:** Java 17+, Maven 3.8+, Chrome installed. No WebDriver binaries — Selenium Manager fetches them. + +**1. `pom.xml`** + +```xml + + 17 + + + + + io.github.seleniumboot + selenium-boot + 3.2.0 + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.11.0 + + + org.apache.maven.plugins + maven-surefire-plugin + 3.2.5 + + + +``` + +**2. `selenium-boot.yml`** — project root, next to `pom.xml`. This is the complete minimum; every key below is required. + +```yaml +execution: + mode: local + baseUrl: https://example.com + +browser: + name: chrome + +timeouts: + explicit: 10 + pageLoad: 30 +``` + +**3. `src/test/java/SmokeTest.java`** + +```java +import com.seleniumboot.test.BaseTest; +import org.testng.annotations.Test; + +import static org.testng.Assert.assertTrue; + +public class SmokeTest extends BaseTest { + + @Test + public void opensThePage() { + open(); + assertTrue(getDriver().getTitle().contains("Example Domain")); + } +} +``` + +Then: + +```bash +mvn test +``` + +No driver setup, no teardown, no waits, no `WebDriver` to manage — `BaseTest` owns the lifecycle. The HTML report lands at `target/selenium-boot-report.html`. + +Next: [the full Getting Started walkthrough](#getting-started) adds page objects, parallel execution, and reporting. --- @@ -30,7 +112,7 @@ It eliminates repetitive boilerplate by providing sensible defaults, a standardi Selenium Boot is **the Spring Boot of Java test automation** — and that positioning is deliberately layered: -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; `SeleniumBootDefaults` covers you if you never write it. +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` stays short — a handful of required keys, and `SeleniumBootDefaults` covers the rest. 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 down to `WebDriver` / `By` / `WebElement`. Opinionated without being a cage. 3. **Extensible toolkit (the escape hatch).** An SPI/registry plugin system (`DriverProviderRegistry`, `PluginRegistry`, `ReportAdapterRegistry`) makes it modular for the power users who need it — serving the opinionated core, not replacing it. Most users never touch it. @@ -90,11 +172,20 @@ Add to your `pom.xml`: ``` -Also add the Surefire plugin so `mvn test` discovers TestNG tests: +Also pin the compiler plugin and add Surefire so `mvn test` discovers TestNG tests: ```xml + + 17 + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.11.0 + org.apache.maven.plugins maven-surefire-plugin @@ -104,6 +195,8 @@ Also add the Surefire plugin so `mvn test` discovers TestNG tests: ``` +> Pinning `maven-compiler-plugin` matters: on Maven 3.8.x and earlier the default compiler level falls back to source/target 5, and the build fails with *"Source option 5 is no longer supported"* on any modern JDK. + --- ### Step 2: Create the Configuration File @@ -136,7 +229,7 @@ timeouts: pageLoad: 30 # seconds ``` -That is the only configuration file needed. All fields have defaults — start with the minimum: +That is the only configuration file needed, and it is **required** — Selenium Boot fails fast at startup if it is missing. Most fields are optional, but `execution.mode`, `browser.name` (or `browser.matrix`), and both `timeouts` values are validated and must be present: ```yaml execution: @@ -145,6 +238,10 @@ execution: browser: name: chrome + +timeouts: + explicit: 10 + pageLoad: 30 ``` ---