feat(driver): expose Ferrum downloads as Driver#downloads

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [Unreleased](https://github.com/rubycdp/cuprite/compare/v0.19...main) ##
 
 ### Added
+- `Driver#downloads` to wait for downloads and list them, files are saved to `Capybara.save_path` [#181]
 
 ### Changed
 

docs/18-downloads.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 18
+---
+
+# Downloads
+
+Files are saved to `Capybara.save_path`, or to the `:save_path` driver option
+if given. `page.driver.downloads` is Ferrum's
+[downloads](/docs/ferrum/downloads) object for the current page.
+
+#### wait(timeout = 5)
+
+Waits until the current download is finished. Pass a block that starts it.
+
+```ruby
+page.driver.downloads.wait { click_link "Export" }
+```
+
+#### files : `Array<Hash>`
+
+Returns information about files downloaded since the last reset.
+
+```ruby
+page.driver.downloads.files.last
+# => {"url"=>"http://127.0.0.1/export.csv", "suggestedFilename"=>"export.csv", "totalBytes"=>4911,
+#     "receivedBytes"=>4911, "state"=>"completed", ...}
+
+File.read(File.join(Capybara.save_path, "export.csv"))
+```
+
+The list is cleared at the end of every test, files on disk are not removed.

lib/capybara/cuprite/driver.rb

@@ -14,7 +14,7 @@ class Driver < Capybara::Driver::Base
 
       delegate %i[restart quit status_code timeout timeout= current_url title body
                   window_handles close_window switch_to_window within_window window_handle
-                  back forward refresh wait_for_reload viewport_size device_pixel_ratio] => :browser
+                  back forward refresh wait_for_reload viewport_size device_pixel_ratio downloads] => :browser
       delegate %i[send_keys] => :active_element
       alias html body
       alias current_window_handle window_handle

spec/features/driver_spec.rb

@@ -930,6 +930,24 @@ def create_screenshot(file, *args)
         end
       end
 
+      context "downloads" do
+        it "saves files to Capybara.save_path" do
+          @driver.downloads.wait { @session.visit("/cuprite/attachment.txt") }
+
+          file = @driver.downloads.files.last
+          expect(file["suggestedFilename"]).to eq("attachment.txt")
+          expect(file["state"]).to eq("completed")
+          expect(File.read(File.join(Capybara.save_path, "attachment.txt"))).to eq("attachment contents")
+        end
+
+        it "forgets files after reset" do
+          @driver.downloads.wait { @session.visit("/cuprite/attachment.txt") }
+          @driver.reset!
+
+          expect(@driver.downloads.files).to be_empty
+        end
+      end
+
       context "cookies support" do
         it "returns set cookies" do
           @session.visit("/set_cookie")

spec/support/test_app.rb

@@ -98,6 +98,11 @@ def authorized?(login, password)
     render_string("Cacheable request <a href='/cuprite/cacheable'>click me</a>")
   end
 
+  get "/cuprite/attachment.txt" do
+    attachment "attachment.txt"
+    "attachment contents"
+  end
+
   get "/cuprite/:view" do |view|
     render_view view
   end