Skip to content

feat(context): add wait_for_new_page, a block for pages and deprecate windows - #711

Merged
route merged 3 commits into
mainfrom
feat/page-popups
Nov 20, 2026
Merged

route merged 3 commits into
mainfrom
feat/page-popups

Conversation

@route

@route route commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

What

  • context.wait_for_new_page { ... } runs the block and returns the page it opens, in a tab or a window, e.g. through window.open or a link with target="_blank". It returns nil if no page opens in time, wait_for_new_page! raises Ferrum::TimeoutError instead. opener: limits it to the pages opened by one page, timeout: bounds the block and the new page together. browser.wait_for_new_page is the default context's.
  • pages of a context and of the browser takes a block that selects targets, so pages(&:opener_id) returns the pages opened by another page.
  • context.windows (and browser.windows) and target.window? are deprecated and will be removed in 0.22.
opened = browser.wait_for_new_page { browser.at_css("a[target=_blank]").click }
opened = context.wait_for_new_page!(opener: page) { page.at_css("a").click }
browser.pages(&:opener_id)

Why

windows listed only the pages another page had opened and was used as windows(:last) to pick the one just opened by its position in a list. It also called those pages "windows", while window_id, window_bounds and :window_size are about the OS window.

wait_for_new_page returns the opened page directly: the call is registered before the block runs and the context matches the opener id of each new page target against it, so a page that opens before the block returns is not missed. Pages and targets still only know ids.

The block of pages filters targets before connecting to them, so the pages it leaves out are not attached to.

Notes

wait_for_new_page runs a block and returns the page it opens, in a tab or a window, with opener: only the pages
opened by that page. The context matches the opener id of each new page target against the waiting calls, so
neither pages nor targets need to know each other.
windows only listed the pages another page opened and was used to pick the one just opened by its position.
wait_for_new_page returns that page directly, so windows warns now and goes away in 0.22. Target#window? goes with
it, it called a page with an opener a window, opener_id says the same.
@route route changed the title feat(context): add wait_for_page and deprecate windows feat(context): add wait_for_new_page, a block for pages and deprecate windows Nov 20, 2026
@route
route merged commit 49f6e6b into main Nov 20, 2026
7 checks passed
@route
route deleted the feat/page-popups branch November 20, 2026 17:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant