From 878a549017e813bb11fffdbd6ea6791fdb9dad0c Mon Sep 17 00:00:00 2001
From: Dmitry Vorotilin <d.vorotilin@gmail.com>
Date: Fri, 30 Oct 2026 12:55:34 +0300
Subject: [PATCH] ref(frame): deprecate current_url and current_title in favor
 of url and title

On a page current_url and current_title return the same as url and title, and on a frame they return the top
window's, which reads as the frame's own and raises from a cross-origin frame. Use page.url, or frame.page.url
from a frame; they will be removed in 0.22.
---
 CHANGELOG.md             |  4 ++++
 docs/15-frames.md        | 17 ++++-------------
 docs/3-navigation.md     |  2 +-
 docs/4-finders.md        | 14 ++++++++------
 lib/ferrum/frame/dom.rb  | 22 ++++++++++++++--------
 sig/ferrum/frame/dom.rbs |  4 ++--
 spec/browser_spec.rb     |  2 +-
 spec/frame_spec.rb       | 27 +++++++++++++++++++++++----
 spec/node_spec.rb        | 10 +++++-----
 spec/page_spec.rb        | 26 +++++++++++++-------------
 10 files changed, 75 insertions(+), 53 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d8eebc9..4c016e9d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@
   statements run and the last one's value is returned, and `Node#evaluate` returns nodes and dates, see
   [upgrading](docs/13-javascript.md#upgrading-to-021) [#673]
 
+### Deprecated
+- `current_url` and `current_title` on pages and frames, will be removed in 0.22. Use `url` and `title`, or
+  `frame.page.url` for the top window from a frame, `frame.url` is the frame's own
+
 ### Fixed
 
 ### Removed
diff --git a/docs/15-frames.md b/docs/15-frames.md
index 593182b5..85f47ef2 100644
--- a/docs/15-frames.md
+++ b/docs/15-frames.md
@@ -125,24 +125,15 @@ frame = page.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
 frame.main? # => false
 ```
 
-#### current_url : `String`
+#### page : `Page`
 
-Returns current frame's top window location href.
+The page the frame belongs to, use `frame.page.url` and `frame.page.title` for the top window. `current_url` and
+`current_title` are deprecated and will be removed in 0.22.
 
 ```ruby
 page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
 frame = page.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
-frame.current_url # => "https://www.w3schools.com/tags/tag_frame.asp"
-```
-
-#### current_title : `String`
-
-Returns current frame's top window title.
-
-```ruby
-page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
-frame = page.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
-frame.current_title # => "HTML frame tag"
+frame.page.url # => "https://www.w3schools.com/tags/tag_frame.asp"
 ```
 
 #### body : `String`
diff --git a/docs/3-navigation.md b/docs/3-navigation.md
index 8d617602..90f88293 100644
--- a/docs/3-navigation.md
+++ b/docs/3-navigation.md
@@ -64,7 +64,7 @@ JavaScript.
 
 ```ruby
 page.wait_for_navigation { page.at_css("a").evaluate("this.click()") } # => true
-page.current_url # => the link's page
+page.url # => the link's page
 ```
 
 #### wait_for_navigation!(wait = 0.1) { }
diff --git a/docs/4-finders.md b/docs/4-finders.md
index d1f65b4c..e85087dc 100644
--- a/docs/4-finders.md
+++ b/docs/4-finders.md
@@ -58,24 +58,26 @@ page.go_to("https://github.com/")
 page.xpath("//a[@aria-label='Issues you created']") # => [Node]
 ```
 
-#### current_url : `String`
+#### url : `String`
 
-Returns current top window location href.
+Returns the page's location href. On a frame `url` is that frame's own, see [Frames](/docs/ferrum/frames).
 
 ```ruby
 page.go_to("https://google.com/")
-page.current_url # => "https://www.google.com/"
+page.url # => "https://www.google.com/"
 ```
 
-#### current_title : `String`
+#### title : `String`
 
-Returns current top window title
+Returns the page's title.
 
 ```ruby
 page.go_to("https://google.com/")
-page.current_title # => "Google"
+page.title # => "Google"
 ```
 
+`current_url` and `current_title` are deprecated and will be removed in 0.22, use `url` and `title`.
+
 #### body : `String`
 
 Returns current page's html.
diff --git a/lib/ferrum/frame/dom.rb b/lib/ferrum/frame/dom.rb
index 8ff8b0c2..5b53e031 100644
--- a/lib/ferrum/frame/dom.rb
+++ b/lib/ferrum/frame/dom.rb
@@ -61,31 +61,37 @@ module DOM
         }
       JS
 
+      #
+      # @deprecated Will be removed in Ferrum 0.22. Use `page.url`, or
+      #   `frame.page.url` from a frame.
       #
       # Returns current top window `location href`.
       #
       # @return [String]
       #   The window's current URL.
       #
-      # @example
-      #   browser.go_to("https://google.com/")
-      #   browser.current_url # => "https://www.google.com/"
-      #
       def current_url
+        Utils::Deprecate.warn(
+          "#current_url will be removed in Ferrum 0.22. Use page.url, or frame.page.url from a frame, " \
+          "frame.url is the frame's own URL."
+        )
         evaluate("window.top.location.href")
       end
 
+      #
+      # @deprecated Will be removed in Ferrum 0.22. Use `page.title`, or
+      #   `frame.page.title` from a frame.
       #
       # Returns current top window title.
       #
       # @return [String]
       #   The window's current title.
       #
-      # @example
-      #   browser.go_to("https://google.com/")
-      #   browser.current_title # => "Google"
-      #
       def current_title
+        Utils::Deprecate.warn(
+          "#current_title will be removed in Ferrum 0.22. Use page.title, or frame.page.title from a frame, " \
+          "frame.title is the frame's own title."
+        )
         evaluate("window.top.document.title")
       end
 
diff --git a/sig/ferrum/frame/dom.rbs b/sig/ferrum/frame/dom.rbs
index 4795d6a0..cbe53c40 100644
--- a/sig/ferrum/frame/dom.rbs
+++ b/sig/ferrum/frame/dom.rbs
@@ -9,9 +9,9 @@ module Ferrum
 
       LINK_TAG: ::String
 
-      def current_url: () -> untyped
+      %a{deprecated} def current_url: () -> untyped
 
-      def current_title: () -> untyped
+      %a{deprecated} def current_title: () -> untyped
 
       def doctype: () -> untyped
 
diff --git a/spec/browser_spec.rb b/spec/browser_spec.rb
index 13e9bbbe..fe0ed703 100644
--- a/spec/browser_spec.rb
+++ b/spec/browser_spec.rb
@@ -1141,7 +1141,7 @@ def proxy_tunnel(socket, request, browser_url)
         browser.go_to("http://example.com")
         puts "Please type enter"
         sleep 1
-        browser.current_url
+        browser.url
       RUBY
     end
 
diff --git a/spec/frame_spec.rb b/spec/frame_spec.rb
index c3127df8..8dda8a36 100644
--- a/spec/frame_spec.rb
+++ b/spec/frame_spec.rb
@@ -64,13 +64,13 @@
 
   it "waits for the cross-domain frame to load" do
     page.go_to("/frames")
-    expect(page.current_url).to eq(base_url("/frames"))
+    expect(page.url).to eq(base_url("/frames"))
     frame = page.at_xpath("//iframe[@name='frame']").frame
 
     expect(frame.url).to end_with("/slow")
     expect(frame.body).to include("slow page")
 
-    expect(page.current_url).to end_with("/frames")
+    expect(page.url).to end_with("/frames")
   end
 
   context "with src == about:blank" do
@@ -129,7 +129,7 @@
     page.go_to("/inline_pdf")
     page.at_css("button").click
 
-    expect(page.current_url).to eq(base_url("/inline.pdf"))
+    expect(page.url).to eq(base_url("/inline.pdf"))
     expect(page.network.response.content_type).to eq("application/pdf")
   end
 
@@ -221,7 +221,26 @@
 
     frame = page.at_xpath("//iframe").frame
     expect(frame.url).to end_with("/slow")
-    expect(page.current_url).to end_with("/frames")
+    expect(page.url).to end_with("/frames")
+  end
+
+  describe "#current_url and #current_title" do
+    around do |example|
+      Ferrum::Utils::Deprecate.reset!
+      example.run
+      Ferrum::Utils::Deprecate.reset!
+    end
+
+    it "return the top window's and warn that they are deprecated" do
+      page.go_to
+      page.execute(%(document.body.innerHTML += "<iframe src='/slow' name='frame'>"))
+      frame = page.at_xpath("//iframe[@name='frame']").frame
+
+      expect { expect(frame.current_url).to eq(page.url) }
+        .to output(/#current_url will be removed in Ferrum 0\.22.*called from #{__FILE__}/m).to_stderr
+      expect { expect(frame.current_title).to eq(page.title) }
+        .to output(/#current_title will be removed in Ferrum 0\.22/).to_stderr
+    end
   end
 
   it "can set page content" do
diff --git a/spec/node_spec.rb b/spec/node_spec.rb
index 1c1fd2f2..6ada0e11 100644
--- a/spec/node_spec.rb
+++ b/spec/node_spec.rb
@@ -7,7 +7,7 @@
 
       browser.at_xpath("//a[span[text() = 'Hidden link']]").click
 
-      expect(browser.current_url).to eq(base_url("/"))
+      expect(browser.url).to eq(base_url("/"))
     end
 
     it "fires a ping request for anchor elements" do
@@ -40,7 +40,7 @@
 
         link.click
 
-        expect(browser.current_url).to eq(base_url("/"))
+        expect(browser.url).to eq(base_url("/"))
       end
     end
 
@@ -134,7 +134,7 @@
       it "scrolls into view if element outside viewport" do
         link = page.at_xpath("//a[text() = 'Link outside viewport']")
         link.click
-        expect(page.current_url).to eq(base_url("/scroll"))
+        expect(page.url).to eq(base_url("/scroll"))
 
         expect(link.in_viewport?).to eq(true)
         box = page.at_xpath("//div[@id='overflow-box']")
@@ -143,7 +143,7 @@
         link.scroll_into_view
         expect(link.in_viewport?(of: box)).to eq(true)
         link.click
-        expect(page.current_url).to eq(base_url("/"))
+        expect(page.url).to eq(base_url("/"))
       end
 
       it "scrolls into view if element below the fold" do
@@ -154,7 +154,7 @@
 
         expect(link.in_viewport?).to eq(true)
         link.click
-        expect(page.current_url).to eq(base_url("/"))
+        expect(page.url).to eq(base_url("/"))
       end
     end
 
diff --git a/spec/page_spec.rb b/spec/page_spec.rb
index 272a6d57..0dbf15fd 100644
--- a/spec/page_spec.rb
+++ b/spec/page_spec.rb
@@ -67,47 +67,47 @@
     end
   end
 
-  describe "#current_url" do
+  describe "#url" do
     it "supports whitespace characters" do
       page.go_to("/arbitrary_path/200/foo%20bar%20baz")
 
-      expect(page.current_url).to eq(base_url("/arbitrary_path/200/foo%20bar%20baz"))
+      expect(page.url).to eq(base_url("/arbitrary_path/200/foo%20bar%20baz"))
     end
 
     it "supports escaped characters" do
       page.go_to("/arbitrary_path/200/foo?a%5Bb%5D=c")
 
-      expect(page.current_url).to eq(base_url("/arbitrary_path/200/foo?a%5Bb%5D=c"))
+      expect(page.url).to eq(base_url("/arbitrary_path/200/foo?a%5Bb%5D=c"))
     end
 
     it "supports url in parameter" do
       page.go_to("/arbitrary_path/200/foo%20asd?a=http://example.com/asd%20asd")
 
-      expect(page.current_url).to eq(base_url("/arbitrary_path/200/foo%20asd?a=http://example.com/asd%20asd"))
+      expect(page.url).to eq(base_url("/arbitrary_path/200/foo%20asd?a=http://example.com/asd%20asd"))
     end
 
     it "supports restricted characters ' []:/+&='" do
       page.go_to("/arbitrary_path/200/foo?a=%20%5B%5D%3A%2F%2B%26%3D")
 
-      expect(page.current_url).to eq(base_url("/arbitrary_path/200/foo?a=%20%5B%5D%3A%2F%2B%26%3D"))
+      expect(page.url).to eq(base_url("/arbitrary_path/200/foo?a=%20%5B%5D%3A%2F%2B%26%3D"))
     end
 
     it "returns about:blank when on about:blank" do
       page.go_to("about:blank")
 
-      expect(page.current_url).to eq("about:blank")
+      expect(page.url).to eq("about:blank")
     end
 
     it "handles hash changes" do
       page.go_to("/#omg")
-      expect(page.current_url).to match(%r{/#omg$})
+      expect(page.url).to match(%r{/#omg$})
       page.execute <<-JS
         window.onhashchange = function() { window.last_hashchange = window.location.hash }
       JS
 
       page.go_to("/#foo")
 
-      expect(page.current_url).to match(%r{/#foo$})
+      expect(page.url).to match(%r{/#foo$})
       expect(page.evaluate("window.last_hashchange")).to eq("#foo")
     end
   end
@@ -118,9 +118,9 @@
 
       page.execute(%(window.history.pushState({foo: "bar"}, "title", "bar2.html");))
 
-      expect(page.current_url).to eq(base_url("/bar2.html"))
+      expect(page.url).to eq(base_url("/bar2.html"))
       expect { page.back }.not_to raise_error
-      expect(page.current_url).to eq(base_url("/"))
+      expect(page.url).to eq(base_url("/"))
     end
   end
 
@@ -129,13 +129,13 @@
       page.go_to
 
       page.execute(%(window.history.pushState({foo: "bar"}, "title", "bar2.html");))
-      expect(page.current_url).to eq(base_url("/bar2.html"))
+      expect(page.url).to eq(base_url("/bar2.html"))
       # don't use #back here to isolate the test
       page.execute("window.history.go(-1);")
 
-      expect(page.current_url).to eq(base_url("/"))
+      expect(page.url).to eq(base_url("/"))
       expect { page.forward }.not_to raise_error
-      expect(page.current_url).to eq(base_url("/bar2.html"))
+      expect(page.url).to eq(base_url("/bar2.html"))
     end
   end