Installing Capybara-WebKit On MacOS Mojave
I’ve recently upgraded to a Macbook Pro 2019 and need to setup my local development environment in MacOS Mojave. As a Ruby on Rails developer, there’s a shortlist of Ruby gems that always seem to put a fight when I run
bundle install and the
capybara-webkit gem has proven to be one of the worst. This post outlines the steps needed to install the
capybara-webkit gem on a fresh copy of MacOS Mojave (10.14.6), hopefully saving you an hour of Google searching.
Many Ruby on Rails projects use
capybara-webkit gem depends on some software called Qt and won’t compile on MacOS without some QT libraries (
libqt) being present on your computer.
Step 1: Install Qt 5.5
Our first step is to install the Qt libraries needed to compile and install
capybara-webkit. Ordinarily we’d reach for MacOS’ unofficial package manager, Homebrew, to install our missing software, though the (newer) versions of Qt available via Homebrew no longer have the libraries that
capybara-webkit requires. To ensure we have all the libraries we need, we must manually install an older version of Qt (version 5.5) via this link.
Once we’ve installed Qt 5.5, we need to add its binaries to our system’s path, ensuring they can be found when we next try to build
capybara-webkit. Depending on which Shell you’re using (the Mojave default is Bash), you’ll need to add the following line to your
.zshrc (if you’re using the ZSH shell)
Once you’ve added the above line to your shell’s configuration file, restart your terminal and run
which qmake to ensure the Qt libraries are available. You should see something similar to the output below:
which qmake /Users/your-name/Qt5.5.0/5.5/clang_64/bin/qmake
Step 2: Install XCode 9.4
In order to install
capybara-webkit, we need to compile its source code on your computer. The previous steps gave us the Qt 5.5 libraries on which we depend, though we also need some extra C++ libraries (e.g.
limit.h ) that don’t ship with a fresh copy of MacOS Mojave.
Most of the time we get our compilation headers from XCode.app, free software developed by Apple and available via the Apple App Store. Unfortunately, the specific C++ libraries needed to build
capybara-webkit no longer ship with recent versions of XCode (version 10 and onwards), meaning we need to downgrade to XCode 9.4.
Downgrading is pretty straight forward, simply grab XCode 9.4 from Apple’s Developer pages, extract the
.zip archive and copy the
Xcode app into your
/Applications directory. Finally, restart your terminal and execute the following commands to ensure XCode 9.4 is registered in your terminal and that the terms and conditions have been accepted.
sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer sudo xcodebuild -license agree
Step 3: Install capybara-webkit via Bundler
You’ll be glad to know that the hard work is now done. We’ve installed the development libraries for Qt along with the C++ headers needed for compilation, meaning you should be able to build and install capybara-webkit:
gem install capybara-webkit
I have this helps and happy coding!