From 9d77bd3a3805d9df0b0cfc151bb561c9373a3399 Mon Sep 17 00:00:00 2001
From: Mohammad Saddam Hossain <sddmhossain786@gmail.com>
Date: Thu, 27 Aug 2026 07:28:22 +0530
Subject: [PATCH] docs(readme): show the locator API in the quickstart instead
 of getDriver()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README promises "the productivity features people love in Playwright —
accessibility-first locators, auto-waiting, web-first assertions" in prose, then
never demonstrates them: across 44 code blocks, not one contained a getBy* call.
The only code a reader saw in the first 60 seconds was getDriver().getTitle() —
which is indistinguishable from the in-house BaseTest they already have.

The API is real, tested and reachable directly from BaseTest. It just wasn't on
the front page.

- Quickstart now uses getByRole + assertThat(...).isVisible() instead of
  assertTrue(getDriver().getTitle().contains(...)).
- Adds a before/after against plain Selenium: the same sign-in flow with driver
  lifecycle, WebDriverWait and CSS/XPath, next to five lines with none of it.

Verified against PUBLISHED 3.3.0, not the working tree. The quickstart was
extracted verbatim from the README into a clean three-file project matching the
README's own pom and yml, and run against real Chrome via xvfb: green. The
before/after snippet was wrapped and compiled against the same artifact.

Note for anyone re-running it: example.com was redesigned and its link now reads
"Learn more", not "More information...". The new quickstart asserts on the heading
and on the presence of a link, so it does not depend on their copy.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md | 43 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index da69e1d..e9708e2 100644
--- a/README.md
+++ b/README.md
@@ -66,17 +66,17 @@ timeouts:
 **3. `src/test/java/SmokeTest.java`**
 
 ```java
+import com.seleniumboot.locator.Role;
 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"));
+        assertThat(getByRole(Role.HEADING, "Example Domain")).isVisible();
+        assertThat(getByRole(Role.LINK)).isVisible();
     }
 }
 ```
@@ -89,6 +89,43 @@ 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`.
 
+Note what the test *doesn't* contain: no CSS selector, no XPath, no `WebDriverWait`. `getByRole`
+finds elements the way a screen reader does, and `assertThat(...).isVisible()` retries until the
+timeout instead of failing on the first miss. Both are available on every test and page object.
+
+### The same test, written the usual way
+
+Illustrative — a sign-in flow, raw Selenium on the left of the line, Selenium Boot below it.
+
+```java
+// Plain Selenium + TestNG
+WebDriver driver = new ChromeDriver();
+driver.get("https://app.example.com");
+WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
+
+wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("#email")))
+    .sendKeys("ada@example.com");
+driver.findElement(By.cssSelector("#password")).sendKeys("hunter2");
+driver.findElement(By.cssSelector("button.btn-primary[type='submit']")).click();
+wait.until(ExpectedConditions.visibilityOfElementLocated(
+    By.xpath("//*[contains(text(),'Welcome back')]")));
+
+driver.quit();
+```
+
+```java
+// Selenium Boot — same flow
+open();
+getByLabel("Email").type("ada@example.com");
+getByLabel("Password").type("hunter2");
+getByRole(Role.BUTTON, "Sign in").click();
+assertThat(getByText("Welcome back")).isVisible();
+```
+
+The second version has no driver lifecycle, no explicit waits, and nothing coupled to the
+markup — rename a CSS class or reorder the DOM and it still passes. The raw `WebDriver` is
+still there via `getDriver()` whenever you need it.
+
 Next: [the full Getting Started walkthrough](#getting-started) adds page objects, parallel execution, and reporting.
 
 ---