This article is all about setting up Cucumber on OSX. Specifically, it’s for people who just want a list of things to do and who know their way around their Mac a little bit already. If that’s not you and you’d prefer a step by step guide that explains everything then click here for my guide for absolute beginners. Or flick between the two. It’s entirely up to you.

You are in luck. It’s a bit easier to install Cucumber (and everything it needs) on an Apple than it is on other computers.

Installing Ruby with Rbenv and Homebrew

To start out, we’re going to install Homebrew, a third party package manager for Apple. To install Homebrew, navigate to http://brew.sh/ in your favourite browser. You’ll see that near the top there’s a curl command you need to copy to install it. Simply copy that into your clipboard and paste it into your terminal window then hit return to run it. You’ll need Xcode installed, but if you don’t have it you will see a pop up in the middle of the installation.

Now, we need to install Ruby. I have used RBENV to manage my Ruby installations for years. To install RBENV, simply use the following command in your terminal: brew install rbenv ruby-build

Next, we need to add a line to your .bash_profile file, which is where the settings for your terminal are stored. You don’t need to find it, we can do it all with one command. Run the following command in your terminal window: echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

Then either shut down and reload your terminal window or run this command to reload your .bash_profile file so your current terminal window is up to date: source ~/.bash_profile

Now you can go and install as many ruby versions as you like, although it’s best to start with just one. I’ve been using version 2.1.3 for a while so go ahead and install that version with the following command: rbenv install 2.1.3

Use this command to set that as your global Ruby version: rbenv global 2.1.3

And that’s it! Type in ruby -v and hit return. Your terminal will now tell you that you’re now using Ruby 2.1.3.

Installing Bundler and other gems

Ruby doesn’t come with a package manager already installed, like some languages do, but there is a particularly good one available to us called Bundler. At your terminal, type in gem install bundler and hit return. Once that’s done, we can use Bundler to install a bunch of gems all at once. For that we need a Gemfile.

Load Finder and navigate to where you want to create your cucumber project. Personally, I always create a ‘code’ folder in my home directory, but it can be anywhere you like. You can put it on the desktop if you prefer. Wherever you have chosen, right click and select ‘New Folder’ and call it something like cucumber_project. Now that we have our project folder, we can go about creating a Gemfile.

For this, we will need a text editor.

Installing Sublime Text 2 and creating a Gemfile to install multiple gems

I use Sublime Text 2. To install it, go to http://www.sublimetext.com/ and click the ‘Download for OSX’ button. This will download it for you. All you need to do now is open your downloads folder, double click the installation file and then drag the Sublime Text icon into your Applications folder (a shortcut will be next to it).

Now we have Sublime Text installed, simply load it then copy and paste the example below into the empty page that will have loaded:

source 'https://rubygems.org'
gem 'cucumber', '1.3.18'
gem 'capybara', '2.4.4'
gem 'selenium-webdriver', '2.46.2'

The gems we are installing are Cucumber (which you know about already, I assume, as that’s why you are here), Capybara (which is a handy framework that makes writing your tests very easy) and Selenium Webdriver (we will use this to replicate a user using a website on an internet browser).

Now, save that as ‘Gemfile’ in your project directory.

Now type in bundle install and hit return. Bundler will now go and install each gem in turn, along with all their dependencies.

We now have all the gems we need to make a good start so let’s create the directory structure we need. It’s probably easiest in Finder. Once in your project directory you will see that our Gemfile is there waiting for you. Leave that where it is and create a folder called ‘features’ with a lower case ‘f’. This is where most other files and folders will live, with regards to Cucumber. Double click on ‘features’ and, once inside, create two more folders: ‘step_definitions’ and ‘support’.

At this point, I’m going to assume you’ve been using Sublime Text, like me, so I will recommend installing a few add packages. Load up your favourite internet browser and go to http://packagecontrol.io where you will find instructions on how to install the Sublime text Package Manager. Once it has restarted all it wants to, you can install a few packages. Simply press ‘cmd’, ‘shift’ and ‘P’ all at once and you will see a command prompt appear. Type in ‘install package’ and you should see ‘Package Control: Install Package’ highlighted when you can select return.

There are a few packages that I use regularly. For now, we’ll install the most useful.

Once you’ve selected to install a package, type in cucumber and you will see a few packages to choose from. The most useful, for me, is the Gherkin (Cucumber) Formatter, which gives you nice syntax highlighting on your Cucumber features. You can also search for ruby and install RubyTest, if you like. With RubyTest installed, you can place your cursor in a Cucumber scenario and run it in Sublime Text by right clicking and running either the single test or the whole feature. This can be useful if you don’t want to switch between your terminal and Sublime Text.

Installing Firefox

Now that our packages are installed, we can write our Cucumber features and Ruby code. All you need to do now is install Firefox. Later on, in a future article, I’ll explain how to add different webdrivers for browsers such as Google Chrome. For now, we’ll stick with Firefox as it’s the easiest. If you don’t have it installed already, you can click here to download the latest version of Firefox. Now, by the time you read this, Firefox may have been updated. Possibly several times. At the moment, I’m using the latest version (v38.0.5) which works with the latest version of Selenium Webdriver (v2.46.2). However, it’s not unheard of for Firefox to make significant changes with new releases that take Selenium a while to sort out. The best advice I have is to try the latest version of Selenium along with the latest version of Firefox. If that doesn’t work, click here to install a previous version of Firefox. If that still doesn’t work, try an earlier version of Selenium (sometimes Selenium has bugs, too). If you still don’t have any joy, email me or send me a tweet and I’ll let you know what I’m currently using.

Now, you’re ready to start testing! Click here to read my next post about Writing Your First Cucumber Test.