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. It’s an easy way to install applications and to keep them up to date. Installing Homebrew is easy. We simply use a cURL command. cURL is a command line tool for sending and receiving files. You can use it for interrogating a website, as an example. Try it yourself by loading a terminal window, type in the following command curl and then hit return. You should see the output almost immediately. Now, to install Homebrew, navigate to 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, which is Apple’s developer package. Don’t worry though, if you don’t have it installed you will see a pop up in the middle of the installation, asking you if you want to install it. Simply click to install it and then carry on. Further on during the installation you’ll need to type in your password, but that’s ok. Now that we have Homebrew, we can use a variety of brew commands to easily install and maintain software.

Now, we need to install Ruby, which is a programming language and interpreter. Cucumber is written in Ruby and needs it to run. Now, Ruby will already be installed on your Apple, but as it’s used by OSX (the operating system used by Apple), it’s quite well protected. This means that you will be unable to install the relevant Ruby add on packages (we call them Ruby gems) that you will need. It’s possible to fiddle around and enable yourself to do this, but it’s much easier (and safer) to install a Ruby manager. This will enable you to install a secondary version of Ruby that you can use for whatever you like (and keep the original version for your operating system). There are a couple of Ruby managers. RVM is quite popular. I have used RBENV for years so I will talk you through how to install and use that one.

To install RBENV, simply use the following command in your terminal: brew install rbenv ruby-build

This will install it for you. The only other thing you will need to do is add a line to your .bash_profile file, which is just a collection of scripts that are needed when you use your terminal. All you need to do for that is use this command in your terminal window: echo 'eval "$(rbenv init -)"' >> ~/.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

Next, you just need to tell your computer that you want this to be your main Ruby version. Use this command: 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.

Now that you have your second installation of Ruby installed and set up, you don’t need to worry about that again. You can just leave RBENV to work its magic in the background and carry on working as if you only have one version. Whenever you use a Ruby command from now on, RBENV will use this secondary version. So let’s begin to install everything else we need.

Installing Bundler and other gems

As I mentioned earlier, you can install additional Ruby packages to help you with things. These are called gems and they are installed via the gem command. At a command prompt, type in gem list and hit return. You will now see a list of local gems. Local just means they are installed on your computer. You will need to install a few more. It’s easy to install gems individually. All you need to do is use the gem install command, followed by the name of the gem you wish to install (and the version, if you don’t want the latest). However, in the future you may need to install multiple versions of the same gem, so we are going to use a package manager to manage everything for us. 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. Bundler will not only help us install all our gems, it will enable us to have multiple versions of the same gem installed at once and to only use the specific version we need at any one time.

At your terminal, type in gem install bundler and hit return. This will install Bundler for you and all of its dependencies. Once that’s done, we can use Bundler to install a bunch of gems all at once. For that we need a Gemfile.

A Gemfile is a text file that contains information about the gems we want to install and use (and also where we want to install them from). In a moment I will give you an example to copy, but first we need to know where to save it. 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.

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

For this, we will need a text editor. TextEdit comes included with every Apple computer, but if you use that then you’ll have to save your Gemfile with an extension (for example gemfile.rtf) and then delete the extension (the .rtf) afterwards. It’s easier if you install another text editor. I recommend Sublime Text, which I’ve also used for many years. When we start to write our Cucumber tests, you’ll see that Sublime Text makes things much easier by highlighting key words in your code. It costs if you want to use it permanently, but there is a free 30 day trial. Peronally, I think it’s worthwhile buying but you can, of course, use any text editor you wish.

To install it, go to 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 ''
gem 'cucumber', '1.3.18'
gem 'capybara', '2.4.4'
gem 'selenium-webdriver', '2.46.2'

To give you a little information about what that is, the first line (starting with source) is where you want to find your Ruby gems. In most cases, it will be the directory above, but if you work for a company that has its own internal gem store then you can replace it with that location instead. For the purposes of this tutorial, please use the standard location above.

The next few lines are where we identify the gems we want Bundler to install. These are the gems we will be using for our project. We will be adding a few more later, but this will be enough for us to start. Whenever we need to add a gem to this file, the format is exactly the same. It’s the word ‘gem’ followed by the name of the gem in single quotes. We could leave it at that if we wanted and Bundler would install the latest version of each gem. However, we may need to install different versions of the same gem for different projects, so I’ve added version numbers. This is always done with a comma after the name of the gem, followed by the version (also in single quotes). Now that we have defined our specific versions, we can use Bundler to not only install the specific gems we need, but to ensure we always use the right versions of them whenever we use Cucumber. But I’ll come to that later. For now, all we need concern ourselves with is installing the gems we need.

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. Just go to File > Save in the menu bar at the top of Sublime Text. Now that we have our Gemfile, we can navigate to our project folder in our terminal and start to use Bundler. Go back to your terminal window and navigate to your project directory. Mine is my ‘code’ directory so I’m going to type cd ~/code/cucumber_project and hit return. The cd command means change directory and ~ refers to your Home directory. If you created your project folder on the desktop then you will need to type cd ~/Desktop/cucumber_project. If you like, you can type in cd ~ then hit return and go straight to your Home directory. You can then type in ls and hit return. This will tell you what’s in your Home directory. You will see a list of folders and files. Using the cd command, you can navigate to the desktop by typing in cd Desktop and hitting return. If you use the command in cd .. (by typing it in and hitting return), you will be taken up a directory, back to Home. Now you know how to navigate using the terminal, go to your project folder.

Now we will use Bundler. It’s very easy. In your terminal window, simply type in bundle install and hit return. Bundler will now go and install each gem in turn, along with all their dependencies. This shouldn’t take long at all. Once it’s finished, use the `gem list` command again to see all the Ruby gems you now have installed on your computer. Remember, these are installed against your shiny new Ruby installation, thanks to RBENV, so if we ever mess things up, your computer will be ok.

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’. That’s basically all you need, for now. You can create your own custom file structure later, but that’s all Cucumber really needs to make a start. You just need one more file to set up your Cucumber environment and then you can go about writing your automated tests.

At this point, I’m going to assume you’ve been using Sublime Text, like me, so I will recommend installing a few add ons (or packages) that will make things a lot easier. The easiest way to do this is to install the Sublime Text Package Manager. Load up your favourite internet browser and go to where you will find instructions on how to install it. It’s very easy. All you need to do is highlight the code for your particular version of Sublime text and copy it to your clipboard. I’m using Sublime Text 2, so the packages I’ll be recommending will be for that particular version.

Now that you have the code in your clipboard, go back to Sublime Text and press the ‘ctrl’ and ‘`’ keys at the same time. This will launch the Console, which is where you can type in commands. Sublime Text was written in Python, so Python commands can be used. The code you have in your clipboard to install the Package Manager is Python. Python is another scripting language, similar to Ruby, but we won’t go into that now. Once you’ve pasted the code into the Console, hit return and Sublime Text will go away and install the Package Manager. You’ll need to restart Sublime Text a couple of times, but that’s to be expected. It will tell you when you need to do this. 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.

Now that our packages are installed, we can write our Cucumber features and Ruby code with some wonderful syntax highlighting. Syntax highlighting just means that different key words will be in different colours. It makes things a lot easier.

Installing Firefox

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.