Selenium WebDriver Tutorial for QA Test Automation with Java

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class FirstTest {
  public static void main(String[] args) {
    WebDriver driver = new ChromeDriver();
    driver.get("https://thetechworldlabs.com");
    System.out.println("Title: " + driver.getTitle());
    driver.quit();
  }
}

<!-- Selenium Java -->
<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-java</artifactId>
  <version>4.18.1</version>
</dependency>

<!-- TestNG -->
<dependency>
  <groupId>org.testng</groupId>
  <artifactId>testng</artifactId>
  <version>7.9.0</version>
  <scope>test</scope>
</dependency>

import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import org.testng.Assert;
import org.testng.annotations.*;

public class MyFirstTest {
  WebDriver driver;

  @BeforeClass
  public void setUp() {
    driver = new ChromeDriver();
    driver.manage().window().maximize();
  }

  @Test
  public void testPageTitle() {
    driver.get("https://thetechworldlabs.com");
    Assert.assertEquals(driver.getTitle(), "TechWorld Labs");
  }

  @AfterClass
  public void tearDown() { driver.quit(); }
}

// By exact text
By.xpath("//button[text()='Login']")

// Partial text match
By.xpath("//button[contains(text(),'Log')]")

// Parent → child
By.xpath("//form[@id='loginForm']//input[@type='email']")

// CSS equivalent
By.cssSelector("form#loginForm input[type='email']")

// Contains class
By.cssSelector("button[class*='btn-primary']")

// Click & type
driver.findElement(By.id("submit")).click();
driver.findElement(By.name("email")).sendKeys("[email protected]");

// Dropdown using Select class
Select dropdown = new Select(driver.findElement(By.id("country")));
dropdown.selectByVisibleText("");
dropdown.selectByValue("np");
dropdown.selectByIndex(2);

// Advanced: hover, drag-and-drop
Actions actions = new Actions(driver);
actions.moveToElement(element).perform();
actions.doubleClick(element).perform();
actions.dragAndDrop(source, target).perform();

// Handle alert popup
Alert alert = driver.switchTo().alert();
alert.accept();   // Click OK
alert.dismiss();  // Click Cancel

// Implicit wait — applies to all findElement calls
driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));

// Explicit wait — waits for specific condition
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(15));

WebElement el = wait.until(
  ExpectedConditions.visibilityOfElementLocated(By.id("result"))
);

// Other useful ExpectedConditions
ExpectedConditions.elementToBeClickable(By.id("btn"));
ExpectedConditions.textToBePresentInElement(el, "Success");
ExpectedConditions.urlContains("/dashboard");
ExpectedConditions.alertIsPresent();

import org.testng.annotations.*;
import org.testng.Assert;

public class LoginTest {
  WebDriver driver;

  @BeforeClass
  public void classSetup() { driver = new ChromeDriver(); }

  @BeforeMethod
  public void methodSetup() { driver.get("https://example.com"); }

  @Test(priority = 1)
  public void testValidLogin() {
    Assert.assertTrue(driver.getCurrentUrl().contains("/dashboard"));
  }

  @Test(dataProvider = "loginData")
  public void testLoginDDT(String user, String pass) {
    /* runs for each row */
  }

  @DataProvider(name = "loginData")
  public Object[][] getData() {
    return new Object[][] {
      { "user1", "pass1" },
      { "user2", "pass2" }
    };
  }

  @AfterClass
  public void tearDown() { driver.quit(); }
}

public class LoginPage {
  WebDriver driver;
  By emailField  = By.id("email");
  By passField   = By.id("password");
  By loginButton = By.cssSelector("button[type='submit']");
  By errorMsg    = By.className("error-message");

  public LoginPage(WebDriver driver) { this.driver = driver; }

  public void login(String email, String pass) {
    driver.findElement(emailField).sendKeys(email);
    driver.findElement(passField).sendKeys(pass);
    driver.findElement(loginButton).click();
  }

  public String getErrorMessage() {
    return driver.findElement(errorMsg).getText();
  }
}

public class LoginTest {
  WebDriver driver;
  LoginPage loginPage;

  @BeforeClass
  public void setUp() {
    driver    = new ChromeDriver();
    loginPage = new LoginPage(driver);
    driver.get("https://example.com/login");
  }

  @Test
  public void testValidLogin() {
    loginPage.login("[email protected]", "pass123");
    Assert.assertTrue(driver.getCurrentUrl().contains("/dashboard"));
  }

  @AfterClass
  public void tearDown() { driver.quit(); }
}

<dependency>
  <groupId>io.qameta.allure</groupId>
  <artifactId>allure-testng</artifactId>
  <version>2.26.0</version>
</dependency>

# Run tests (generates allure-results/)
mvn clean test

# Generate HTML report
allure generate allure-results --clean -o allure-report

# Open in browser
allure open allure-report

// Save parent window handle
String parentHandle = driver.getWindowHandle();

// Click link that opens new window
driver.findElement(By.linkText("Open New Tab")).click();

// Get all handles and switch to new window
Set<String> allHandles = driver.getWindowHandles();
for (String handle : allHandles) {
  if (!handle.equals(parentHandle)) {
    driver.switchTo().window(handle);
    break;
  }
}
System.out.println("New window: " + driver.getTitle());

// Close child window and switch back
driver.close();
driver.switchTo().window(parentHandle);

// Switch by index
driver.switchTo().frame(0);

// Switch by name or id
driver.switchTo().frame("iframeName");

// Switch by WebElement (most reliable)
WebElement iframe = driver.findElement(By.cssSelector("iframe.content-frame"));
driver.switchTo().frame(iframe);

// Interact inside iframe
driver.findElement(By.id("insideIframe")).click();

// Switch back to main page
driver.switchTo().defaultContent();

// Wait for alert then handle it
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(5));
wait.until(ExpectedConditions.alertIsPresent());

Alert alert = driver.switchTo().alert();
String msg = alert.getText();
System.out.println("Alert says: " + msg);

// Accept (OK)
alert.accept();

// Dismiss (Cancel)
// alert.dismiss();

// Prompt — type text then accept
// alert.sendKeys("My Input"); alert.accept();

JavascriptExecutor js = (JavascriptExecutor) driver;

// Scroll to bottom of page
js.executeScript("window.scrollTo(0, document.body.scrollHeight);");

// Scroll to top
js.executeScript("window.scrollTo(0, 0);");

// Scroll element into view
WebElement el = driver.findElement(By.id("footer"));
js.executeScript("arguments[0].scrollIntoView(true);", el);

// JS click (for hidden/overlapped elements)
js.executeScript("arguments[0].click();", el);

// Set value into a read-only or masked input
js.executeScript("arguments[0].value='2026-04-15';",
  driver.findElement(By.id("datePicker")));

// Get text of a hidden element
String text = (String) js.executeScript(
  "return arguments[0].innerText;", el);

// Highlight element for debugging
js.executeScript(
  "arguments[0].style.border='3px solid red';", el);

// Get page title via JS
String title = (String) js.executeScript("return document.title;");

// Refresh page via JS
js.executeScript("location.reload();");

public class DriverFactory {
  private static ThreadLocal<WebDriver> driver = new ThreadLocal<>();

  public static WebDriver getDriver() { return driver.get(); }

  public static void initDriver(String browser) {
    WebDriver d;
    switch (browser.toLowerCase()) {
      case "firefox": d = new FirefoxDriver(); break;
      case "edge":    d = new EdgeDriver();    break;
      default:         d = new ChromeDriver();
    }
    d.manage().window().maximize();
    d.manage().timeouts().implicitlyWait(Duration.ofSeconds(5));
    driver.set(d);
  }

  public static void quitDriver() {
    if (driver.get() != null) {
      driver.get().quit();
      driver.remove();
    }
  }
}

public class ConfigReader {
  private static Properties props = new Properties();
  static {
    try (InputStream in = ConfigReader.class
        .getResourceAsStream("/config.properties")) {
      props.load(in);
    } catch (IOException e) { throw new RuntimeException(e); }
  }
  public static String get(String key) { return props.getProperty(key); }
}

// config.properties example:
// base.url=https://example.com
// browser=chrome
// timeout=10

public class BaseTest {

  @BeforeMethod
  public void setUp() {
    DriverFactory.initDriver(ConfigReader.get("browser"));
    DriverFactory.getDriver().get(ConfigReader.get("base.url"));
  }

  @AfterMethod
  public void tearDown(ITestResult result) {
    if (result.getStatus() == ITestResult.FAILURE) {
      ScreenshotUtil.capture(DriverFactory.getDriver(), result.getName());
    }
    DriverFactory.quitDriver();
  }
}

public class ScreenshotUtil {
  public static void capture(WebDriver driver, String testName) {
    TakesScreenshot ts = (TakesScreenshot) driver;
    File src = ts.getScreenshotAs(OutputType.FILE);
    String timestamp = new SimpleDateFormat("yyyyMMdd_HHmmss")
        .format(new Date());
    String dest = "target/screenshots/" + testName + "_" + timestamp + ".png";
    try {
      FileUtils.copyFile(src, new File(dest));
      System.out.println("Screenshot saved: " + dest);
    } catch (IOException e) { e.printStackTrace(); }
  }
}

<dependency>
  <groupId>org.apache.poi</groupId>
  <artifactId>poi-ooxml</artifactId>
  <version>5.2.5</version>
</dependency>

import org.apache.poi.xssf.usermodel.*;
import org.apache.poi.ss.usermodel.DataFormatter;

public class ExcelUtil {

  public static Object[][] readData(String filePath, String sheetName)
      throws IOException {

    FileInputStream fis = new FileInputStream(filePath);
    XSSFWorkbook workbook = new XSSFWorkbook(fis);
    XSSFSheet sheet = workbook.getSheet(sheetName);
    DataFormatter fmt = new DataFormatter();

    int rows = sheet.getLastRowNum();   // row 0 = header, excluded
    int cols = sheet.getRow(0).getLastCellNum();
    Object[][] data = new Object[rows][cols];

    for (int r = 1; r <= rows; r++) {
      XSSFRow row = sheet.getRow(r);
      for (int c = 0; c < cols; c++) {
        data[r - 1][c] = fmt.formatCellValue(row.getCell(c));
      }
    }
    workbook.close();
    return data;
  }
}

@DataProvider(name = "loginExcel")
public Object[][] excelData() throws IOException {
  return ExcelUtil.readData(
    "src/test/resources/testdata/loginData.xlsx",
    "LoginSheet");
}

@Test(dataProvider = "loginExcel")
public void testLoginWithExcel(String username, String password) {
  loginPage.login(username, password);
  Assert.assertTrue(
    driver.getCurrentUrl().contains("/dashboard"),
    "Login failed for: " + username);
}

# Download selenium-server-4.x.jar, then:
java -jar selenium-server-4.18.0.jar standalone

# Hub and Node separately:
java -jar selenium-server-4.18.0.jar hub
java -jar selenium-server-4.18.0.jar node --hub http://localhost:4444

version: "3"
services:
  selenium-hub:
    image: selenium/hub:4.18.0
    ports: ["4444:4444"]

  chrome:
    image: selenium/node-chrome:4.18.0
    depends_on: [selenium-hub]
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub

  firefox:
    image: selenium/node-firefox:4.18.0
    depends_on: [selenium-hub]
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub

ChromeOptions options = new ChromeOptions();

WebDriver driver = new RemoteWebDriver(
  new URL("http://localhost:4444"), options);

driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.quit();

<suite name="GridSuite" parallel="methods" thread-count="5">
  <test name="AllTests">
    <classes>
      <class name="tests.LoginTest"/>
      <class name="tests.SearchTest"/>
    </classes>
  </test>
</suite>

name: Selenium Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Run Selenium Tests
        run: mvn clean test -Dbrowser=chrome-headless -Denv=qa

      - name: Upload Allure Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: allure-results
          path: allure-results/

pipeline {
  agent any
  stages {
    stage('Checkout') {
      steps { checkout scm }
    }
    stage('Test') {
      steps {
        sh 'mvn clean test -Dbrowser=chrome-headless'
      }
    }
  }
  post {
    always {
      publishHTML(target: [
        reportDir: 'allure-report',
        reportFiles: 'index.html',
        reportName: 'Allure Report'
      ])
    }
    failure {
      mail to: 'qa-team@company.com',
           subject: "FAILED: ${env.JOB_NAME}",
           body: "Build ${env.BUILD_URL} failed."
    }
  }
}

public static WebDriver createDriver(String browser) {
  return switch (browser.toLowerCase()) {
    case "firefox" -> new FirefoxDriver(new FirefoxOptions());
    case "edge"    -> new EdgeDriver(new EdgeOptions());
    default         -> new ChromeDriver(new ChromeOptions());
  };
}

// Headless Chrome (Chrome 112+)
ChromeOptions chromeOpts = new ChromeOptions();
chromeOpts.addArguments("--headless=new");
chromeOpts.addArguments("--window-size=1920,1080");
chromeOpts.addArguments("--no-sandbox");          // required in Docker
chromeOpts.addArguments("--disable-dev-shm-usage"); // required in Docker
WebDriver driver = new ChromeDriver(chromeOpts);

// Headless Firefox
FirefoxOptions ffOpts = new FirefoxOptions();
ffOpts.addArguments("-headless");
WebDriver ffDriver = new FirefoxDriver(ffOpts);

<suite name="CrossBrowser" parallel="tests" thread-count="3">
  <test name="Chrome">
    <parameter name="browser" value="chrome"/>
    <classes><class name="tests.LoginTest"/></classes>
  </test>
  <test name="Firefox">
    <parameter name="browser" value="firefox"/>
    <classes><class name="tests.LoginTest"/></classes>
  </test>
  <test name="Edge">
    <parameter name="browser" value="edge"/>
    <classes><class name="tests.LoginTest"/></classes>
  </test>
</suite>

// Locate the native file input element
WebElement fileInput = driver.findElement(By.cssSelector("input[type='file']"));

// Send absolute file path — no dialog opens!
String filePath = new File("src/test/resources/testdata/sample.pdf")
    .getAbsolutePath();

fileInput.sendKeys(filePath);

// Verify filename appeared on the page
WebElement fileName = driver.findElement(By.cssSelector(".file-name"));
Assert.assertTrue(fileName.getText().contains("sample.pdf"));

// Submit the form
driver.findElement(By.id("uploadBtn")).click();

JavascriptExecutor js = (JavascriptExecutor) driver;
WebElement fileInput = driver.findElement(By.cssSelector("input[type='file']"));

// Make hidden input visible
js.executeScript("arguments[0].style.display='block';", fileInput);

// Now sendKeys works normally
fileInput.sendKeys(new File("src/test/resources/testdata/image.png")
    .getAbsolutePath());

String downloadPath = System.getProperty("user.home") + "/Downloads/test";

HashMap<String, Object> prefs = new HashMap<>();
prefs.put("download.default_directory", downloadPath);
prefs.put("download.prompt_for_download", false); // no dialog
prefs.put("plugins.always_open_pdf_externally", true); // download PDF

ChromeOptions opts = new ChromeOptions();
opts.setExperimentalOption("prefs", prefs);
WebDriver driver = new ChromeDriver(opts);

// Verify file downloaded — poll until it appears (max 10s)
File downloadedFile = new File(downloadPath + "/report.pdf");
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(d -> downloadedFile.exists());
Assert.assertTrue(downloadedFile.exists(), "File not downloaded!");

driver.get("https://example.com");

Set<Cookie> cookies = driver.manage().getCookies();
for (Cookie c : cookies) {
  System.out.println(c.getName() + " = " + c.getValue());
}

// Get a specific cookie
Cookie sessionCookie = driver.manage().getCookieNamed("JSESSIONID");
System.out.println("Session: " + sessionCookie.getValue());

// Must navigate to domain first
driver.get("https://example.com");

// Add a cookie
Cookie consent = new Cookie.Builder("gdpr_consent", "accepted")
    .domain("example.com")
    .path("/")
    .isSecure(false)
    .build();
driver.manage().addCookie(consent);

// Delete one cookie
driver.manage().deleteCookieNamed("gdpr_consent");

// Delete all cookies (reset session)
driver.manage().deleteAllCookies();

// Step 1: Log in via UI once and capture session cookie
driver.get("https://example.com/login");
driver.findElement(By.id("email")).sendKeys("user@test.com");
driver.findElement(By.id("password")).sendKeys("pass123");
driver.findElement(By.id("loginBtn")).click();

Cookie session = driver.manage().getCookieNamed("session_id");

// Step 2: For subsequent tests — inject cookie, skip login UI
driver.get("https://example.com"); // must visit domain first
driver.manage().addCookie(session);
driver.get("https://example.com/dashboard"); // now logged in!
Assert.assertTrue(driver.getCurrentUrl().contains("/dashboard"));

// Step 1: Find the shadow host element (visible in main DOM)
WebElement shadowHost = driver.findElement(By.cssSelector("my-custom-element"));

// Step 2: Get the shadow root (Selenium 4+ native API)
SearchContext shadowRoot = shadowHost.getShadowRoot();

// Step 3: Find elements inside shadow DOM using CSS only
WebElement inputInsideShadow = shadowRoot.findElement(
    By.cssSelector("input[name='search']"));
inputInsideShadow.sendKeys("Selenium");

// Nested shadow roots
WebElement innerHost = shadowRoot.findElement(By.cssSelector("inner-component"));
SearchContext innerRoot = innerHost.getShadowRoot();
innerRoot.findElement(By.cssSelector("button.submit")).click();

JavascriptExecutor js = (JavascriptExecutor) driver;

// Access shadow root via JS
WebElement shadowHost = driver.findElement(By.cssSelector("my-element"));
WebElement shadowRoot = (WebElement) js.executeScript(
    "return arguments[0].shadowRoot", shadowHost);

// Find inside shadow DOM
WebElement el = (WebElement) js.executeScript(
    "return arguments[0].shadowRoot.querySelector('input')", shadowHost);
el.sendKeys("test");

public void clickWithRetry(By locator, int maxAttempts) {
  for (int i = 0; i < maxAttempts; i++) {
    try {
      driver.findElement(locator).click();
      return; // success — exit
    } catch (StaleElementReferenceException e) {
      if (i == maxAttempts - 1) throw e; // rethrow on last attempt
    }
  }
}

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(15));

// Wait for spinner to disappear
wait.until(ExpectedConditions
    .invisibilityOfElementLocated(By.cssSelector(".loading-spinner")));

// Now the content is ready — interact safely
wait.until(ExpectedConditions
    .visibilityOfElementLocated(By.id("results"))).click();

// Handle dynamic ID — use contains() or data attributes
By.xpath("//button[contains(@id,'submit')]")
By.cssSelector("button[data-action='submit']")