Add instructions on how to use with Chromium?

marckohlbrugge commented 3 years ago

Summary

I recently completely uninstalled Google Chrome for reasons explained here.. This has broken my use of webdrivers, so I'm now trying to switch to Chromium instead.

Whereas webdrivers + Google Chrome seems to work out-of-the-box, getting Chromium to work is a bit more complex. I think step-by-step instructions would be useful for me and other developers.

What I've done so far

brew install --cask chromium

This installs the latest version of Chromium. At the time of writing that's 89.0.4354.0 (Developer Build) (x86_64)

I use webdrivers (4.4.1) with capybara (3.34.0) like this:

Capybara.register_driver :selenium do |app|
  options = Selenium::WebDriver::Chrome::Options.new(
    args: %w[headless disable-gpu no-sandbox disable-dev-shm-usage]
  )
  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
end

This leads to the following error:

        Webdrivers::VersionError:
            Unable to find latest point release version for 89.0.4354. You appear to be using a non-production version of Chrome. Please set `Webdrivers::Chromedriver.required_version = <desired driver version>` to a known chromedriver version: https://chromedriver.storage.googleapis.com/index.html

There is indeed no Chromedriver available for that version number: https://chromedriver.storage.googleapis.com/index.html

So I followed the instructions and set the latest available version:

Webdrivers::Chromedriver.required_version = "88.0.4324.27"

This seems to work. But now I have a hardcoded version number in my app that is bound to get outdated at some point. I've also tried setting it to "LATEST_VERSION" but that didn't work.

Suggestion

Before running into this problem I was oblivious to what chromedriver even was. I just knew that "webdrivers" somehow enabled my Rails system tests to work properly.

And while it's always useful to learn about the tools you're using, I think it would be better if that wasn't required. It would be really nice if using Chromium was as easy as it is using Chrome. Without needing to figure out how chromedriver works, how its versioning matches Chrome's, and that newer version of Chromium might not work out of the box.

Therefore, I suggest to have webdrivers automatically pick the available chromedriver version that's closest to the installed Chromium version (perhaps showing a warning if it's not an exact match), and/or add some instructions to the README that briefly explain how to install a supported version of Chromium that doesn't require specifying a version number for chromedriver.

Also see #180

marckohlbrugge commented 3 years ago

Although everything works in development, I'm now running into issues with my CI workflow on GitHub Actions.

That environment has some version of Chrome installed which requires a different chromedriver version. This is the drawback of manually specifying the version number.

So I'd still be interested in learning how we can use Chromium without hardcoding a version number. Any suggestions?

marckohlbrugge commented 3 years ago

I'm getting closer to an alternative solution where you download an older version of Chromium which has a matching chromedriver version. I'll share instructions on how to find such an older version below, but it's not quite right yet.

I now have Chromium 88.0.4320 installed which has a matching chromedriver: https://chromedriver.storage.googleapis.com/LATEST_RELEASE_88

However, it's not an exact match and webdrivers tries to download LATEST_RELEASE_88.0.4320 which does not exist. Is there a reason it doesn't try to match based on the major version?

Instructions on how to download an older Chromium version (assuming macOS)

Go to https://chromedriver.storage.googleapis.com/LATEST_RELEASE to find the latest available chromedriver version.
Enter that version number into the Lookup tool on https://omahaproxy.appspot.com
You'll get back a "Branch Base Position" like "825209"
Go to https://github.com/Homebrew/homebrew-cask/commits/master/Casks/chromium.rb and find a commit for that number (825209) or lower.
Go to https://commondatastorage.googleapis.com/chromium-browser-snapshots/index.html?prefix=Mac/825209/ where the last part of the URL is the number you found.
Download the chrome-mac.zip file

You can sometimes skip step 4. But if there's no exact match, you'll need to know whichever number is closest. The official documentation suggests trial-and-error and just keep trying decrementing the number. But I find using the Homebrew repository a bit faster as it lets you skip right to the next version for which there's a Mac build.

kapoorlakshya commented 3 years ago

@marckohlbrugge Thanks for all the information! Let's address these one by one:

It would be really nice if using Chromium was as easy as it is using Chrome. Without needing to figure out how chromedriver works, how its versioning matches Chrome's, and that newer version of Chromium might not work out of the box.

Stable versions of both Chrome and Chromium are equally supported by this gem. What's happening in your case is that brew install --cask chromium is downloading the Dev version (see release timeline) of Chromium which does not have a corresponding Dev version of chromedriver on the downloads page. That page only lists the stable and beta release. The Dev drivers are hosted in a separate location that we do not support yet. This leads to you seeing the Unable to find latest point release version for 89.0.4354 error. The workaround for this is to use the latest stable (v87) or beta (v88) version of Chromium instead, and you won't need to manually specify a required_version. It will automatically download the correct driver version for your Chromium version.

I now have Chromium 88.0.4320 installed which has a matching chromedriver: https://chromedriver.storage.googleapis.com/LATEST_RELEASE_88 However, it's not an exact match and webdrivers tries to download LATEST_RELEASE_88.0.4320 which does not exist.

Is there an error message you can share? Asking because LATEST_RELEASE_88.0.4320 actually does exist and should get downloaded - https://chromedriver.storage.googleapis.com/LATEST_RELEASE_88.0.4324.

Is there a reason it doesn't try to match based on the major version?

It matches on the major.minor.build version since v4.4.0 (changelog). This change was made recently to be compliant with the chromedriver version selection guide.

marckohlbrugge commented 3 years ago

Thanks @kapoorlakshya this was very helpful. Downloading an older version has indeed resolved the issue.

Here's two ways to find a stable release for macOS:

https://chromium.woolyss.com (manual download)
https://github.com/mtslzr/homebrew-marmaduke-chromium (using homebrew)

Perhaps this could be added to the README or wiki? Although it's worth pointing out these don't seem like official sources.

Is there an error message you can share? Asking because LATEST_RELEASE_88.0.4320 actually does exist and should get downloaded - https://chromedriver.storage.googleapis.com/LATEST_RELEASE_88.0.4324.

I don't have the error message anymore, but I believe it tried to look for this non-existent file: https://chromedriver.storage.googleapis.com/LATEST_RELEASE_88.0.4320

Note how the version number varies slightly. I guess that technically it means that Chromium version is unsupported.

Anyhow, I've got it resolved now with those two links mentioned above. 👍

kapoorlakshya commented 3 years ago

Thanks @kapoorlakshya this was very helpful. Downloading an older version has indeed resolved the issue.

Great!

I don't have the error message anymore, but I believe it tried to look for this non-existent file: https://chromedriver.storage.googleapis.com/LATEST_RELEASE_88.0.4320

Oops! You are correct. My eyes tricked me and I did not notice the slight difference.

I'll go ahead and close this ticket for now, but feel free to create a new one if you run into issues.

titusfortner / webdrivers