Document: upgrade path to selenium manager

[pboling]

I'm going to document what I find here, because I haven't seen it anywhere else.

In Gemfile

-  gem 'webdrivers', '~> 5.3', '>= 5.3.1'
+  gem 'selenium-devtools', '~> 0.120.0'

Then bundle install

In spec/spec_helper.rb (or other spec harness loader you use):

-  require "webdrivers"
-  Webdrivers::Chromedriver.update

[titusfortner]

Using selenium-devtools should be independent of webdrivers, though if your browser versions are automatically incrementing, I wouldn't lock down the minor version.

[pboling]

I am setting up a new rails 7.2 project with capybara, and on CI webdrivers doesn't install at all. Rather than figure out why I saw that we are encouraged to not use it, so I removed it.

However now that I am thinking about it, I suspect we are using rack-test and not using any of the webdrivers at all.

FWIW, the instructions in the update in the readme are not clear at all.

[titusfortner]

webdrivers doesn't install at all

Yes, it isn't allowed with newer versions of Selenium.

The Readme says:

If you can update to the latest version of Selenium (4.11+), please do so and stop requiring this gem.

Do people really need detailed instructions on how to stop requiring a gem in a project? PRs welcomed, though.

[pboling]

If you can update to the latest version of Selenium (4.11+), please do so and stop requiring this gem.

I don't know what that means. Now that I've read some about it, I have to assume you mean we should be installing a selenium package somehow.

Once we do that... how does it work at all? If we don't have the webdirvers gem, as instructed, how do we specify a web driver in ruby code if there is no longer a webdrivers library? How does Ruby know anything about selenium?

FWIW, I did look at the Ruby instructions on the Selenium web page, and I only ended up more confused.

It certainly looks like there is an upgrade path, and it looks like we should be switching to a gem of a different name. Unfortunately the documentation on Selenium's website is confusing, sparse, and mangled with typos.

It would be nice if this project could include a one liner to make sense of the below, by telling us which gem to use. It seems like I picked the wrong one?

gem install selenium-webdriver
# or
gem 'selenium-devtools', '~> 0.119'
# why is it switching the gem name with no explanation?

I've not yet found an explainer that makes it clear what these two are, how they differ, or why we would pick one over the other.

I'd love to submit a PR, but I don't know what the upgrade path is, which is why I created this issue. It seems that this:

If you can update to the latest version of Selenium (4.11+), please do so and stop requiring this gem

is only half (less than?) of the upgrade.