seleniumboot / seleniumboot/selenium-boot

BasePage.withNewWindow(Runnable) scoping for links that open a new tab

Open
#49 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement good first issue
Dominant language
Java
Stars
12
Forks
6
Avg merge
5h 48m
Merged PRs (30d)
18

Description

Problem

BasePage has a proven pattern for scoping into a nested context and always restoring it — withinFrame(By, Runnable) at src/main/java/com/seleniumboot/test/BasePage.java:353-362, which switches in, runs the action in a try, and restores in finally (with exitFrame() tracking depth via a ThreadLocal). No equivalent exists for windows/tabs — nothing in source calls driver.getWindowHandles() or driver.switchTo().window(...). Today, testing a link that opens in a new tab means hand-rolling the handle-diff dance (snapshot getWindowHandles(), click, diff against the new set, switchTo().window(newHandle), then switch back) in every page object, and a failure mid-block leaves the driver stuck on the new window for the rest of the test.

Why it matters

Without a guaranteed-restore helper, one assertion failure inside a new-tab block silently changes which window every subsequent driver call targets.

Proposed API
// BasePage.java, alongside withinFrame(...)
protected void withNewWindow(Runnable action) {
    // 1. snapshot driver.getWindowHandles()
    // 2. run action
    // 3. diff to find the newly-opened handle, switch to it
    // 4. always switchTo().window(originalHandle) in finally
}

protected void withNewTab(Runnable action); // alias, same behavior

Mirror withinFrame's shape: switch happens automatically based on the handle diff (caller doesn't pass a handle), and restoration is unconditional via finally. Consider whether nesting should track depth the way FRAME_DEPTH does, or whether windows are simple enough to always restore to the single "original" handle.

Acceptance criteria
  • withNewWindow(Runnable) and withNewTab(Runnable) added to BasePage
  • Original window handle is restored in a finally block even if action throws
  • Unit tests (mocked WebDriver/getWindowHandles()) cover: normal open, no new window opened (no-op), and action throwing mid-block
  • Javadoc with a usage example, following the style of withinFrame's doc comment

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/main/java/com/seleniumboot/test/BasePage.java, especially withinFrame(...) at lines 353-362, and inspect the existing window-related tests or test structure. Add both requested helpers with unconditional restoration, document their usage, and cover normal opening, no new window, and an action that throws with mocked WebDriver handles.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
testing-qa
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.