feat: Add Ferrum::Network#wait_for_idle! (#445)

BREAKING CHANGE: `wait_for_idle` now doesn't raise an error. Check your code and replace it with counterpart wait_for_idle!

Author: route

CHANGELOG.md

@@ -2,8 +2,12 @@
 
 ### Added
 
+- `Ferrum::Network#wait_for_idle!` raises an error if timeout reached.
+
 ### Changed
 
+- `Ferrum::Network#wait_for_idle` now returns true or false. Doesn't raise an error [BREAKING CHANGE].
+
 ### Fixed
 
 ### Removed

README.md

@@ -504,9 +504,9 @@ page.go_to("https://github.com/")
 page.network.status # => 200
 ```
 
-#### wait_for_idle(\*\*options)
+#### wait_for_idle(\*\*options) : `Boolean`
 
-Waits for network idle or raises `Ferrum::TimeoutError` error
+Waits for network idle, returns `true` in case of success and `false` if there are still connections.
 
 * options `Hash`
   * :connections `Integer` how many connections are allowed for network to be
@@ -519,7 +519,17 @@ Waits for network idle or raises `Ferrum::TimeoutError` error
 ```ruby
 page.go_to("https://example.com/")
 page.at_xpath("//a[text() = 'No UI changes button']").click
-page.network.wait_for_idle
+page.network.wait_for_idle # => true
+```
+
+#### wait_for_idle!(\*\*options)
+
+Waits for network idle or raises `Ferrum::TimeoutError` error. Accepts same arguments as `wait_for_idle`.
+
+```ruby
+page.go_to("https://example.com/")
+page.at_xpath("//a[text() = 'No UI changes button']").click
+page.network.wait_for_idle! # might raise an error
 ```
 
 #### clear(type)

lib/ferrum/network.rb

@@ -41,7 +41,7 @@ def initialize(page)
     end
 
     #
-    # Waits for network idle or raises {Ferrum::TimeoutError} error.
+    # Waits for network idle.
     #
     # @param [Integer] connections
     #   how many connections are allowed for network to be idling,
@@ -52,21 +52,33 @@ def initialize(page)
     # @param [Float] timeout
     #   During what time we try to check idle.
     #
-    # @raise [Ferrum::TimeoutError]
+    # @return [Boolean]
     #
     # @example
     #   browser.go_to("https://example.com/")
     #   browser.at_xpath("//a[text() = 'No UI changes button']").click
-    #   browser.network.wait_for_idle
+    #   browser.network.wait_for_idle # => false
     #
     def wait_for_idle(connections: 0, duration: 0.05, timeout: @page.timeout)
       start = Utils::ElapsedTime.monotonic_time
 
       until idle?(connections)
-        raise TimeoutError if Utils::ElapsedTime.timeout?(start, timeout)
+        return false if Utils::ElapsedTime.timeout?(start, timeout)
 
         sleep(duration)
       end
+
+      true
+    end
+
+    #
+    # Waits for network idle or raises {Ferrum::TimeoutError} error.
+    # Accepts same arguments as `wait_for_idle`.
+    #
+    # @raise [Ferrum::TimeoutError]
+    def wait_for_idle!(...)
+      result = wait_for_idle(...)
+      raise TimeoutError unless result
     end
 
     def idle?(connections = 0)

spec/network_spec.rb

@@ -36,15 +36,46 @@
     end
   end
 
-  it "#wait_for_idle" do
-    page.go_to("/show_cookies")
-    expect(page.body).not_to include("test_cookie")
+  describe "#wait_for_idle" do
+    it "returns true" do
+      page.go_to("/show_cookies")
+      expect(page.body).not_to include("test_cookie")
 
-    page.at_xpath("//button[text() = 'Set cookie slow']").click
-    network.wait_for_idle
-    page.refresh
+      page.at_xpath("//button[text() = 'Set cookie slow']").click
+      result = network.wait_for_idle
+      page.refresh
+
+      expect(result).to eq(true)
+      expect(page.body).to include("test_cookie")
+    end
+
+    it "returns false" do
+      page.go_to("/show_cookies")
+      expect(page.body).not_to include("test_cookie")
 
-    expect(page.body).to include("test_cookie")
+      page.at_xpath("//button[text() = 'Set cookie slow']").click
+      result = network.wait_for_idle(timeout: 0.2)
+
+      expect(result).to eq(false)
+    end
+  end
+
+  describe "#wait_for_idle!" do
+    it "raises an error" do
+      page.go_to("/show_cookies")
+      expect(page.body).not_to include("test_cookie")
+
+      page.at_xpath("//button[text() = 'Set cookie slow']").click
+      expect { network.wait_for_idle!(timeout: 0.2) }.to raise_error(Ferrum::TimeoutError)
+    end
+
+    it "raises no error" do
+      page.go_to("/show_cookies")
+      expect(page.body).not_to include("test_cookie")
+
+      page.at_xpath("//button[text() = 'Set cookie slow']").click
+      expect { network.wait_for_idle! }.not_to raise_error
+    end
   end
 
   describe "#idle?" do