If you have a Windows machine then setting up Cucumber is a little more difficult, but not that bad. This article is based around installing everything on a Windows 8.1 machine, but the steps will be largely the same for Windows 7. If I have missed something that’s relevant for Windows 7 then let me know in the comments and I’ll add it in.
To start off with we’ll need to install Ruby, which is a programming language and interpreter. Cucumber is written in Ruby and needs it to run. The easiest way to install Ruby is to use the installer. Navigate to http://rubyinstaller.org/ in your favourite internet browser and click on the friendly ‘Download’ button. You’ll be taken to a download page and will be able to choose from a number of versions on the left hand side of the page at the top. Some of the later versions can be a bit buggy. I’ve also had issues with the 64 bit versions, too. For this reason, it’s safest to pick the latest 32 bit version of Ruby 2.0. Currently that’s
Ruby 2.0.0-p645 but it may have advanced when you read this. Click on the latest Ruby 2.0 32 bit version and run it. Select the three checkboxes like the image below, make a note of where you’re installing Ruby (for example
C:/Ruby200) and click
Install to continue.
We also need to install the Ruby Development Kit, which is needed with Cucumber. That’s also easy. On the same page, on the left hand side, you’ll see a few downloads for different versions of the Ruby DevKit. Pick the one for Ruby 2.0 and above and 32 bit Windows. Select to save this one, but don’t run it yet. Whilst it’s downloading, launch Windows Explorer by selecting the Windows key and E at the same time and navigate to where your Ruby installation is. Mine is in
C:/Ruby200. Right click, select New > Folder and call it
devkit. Now, navigate to your
downloads folder. Drag your Ruby DevKit installation file into your newly created
devkit folder and then you can double click it. This will extract a whole bunch of files and folders contained in the Ruby development kit. We’ll now need to run a couple of commands to complete the DevKit installation. You’ll need to run these from your command prompt at the location of where the files have been extracted. The easiest way to do this is to type in
cmd in the path bar in Windows Explorer, like the image below, and hit return. This will launch a new command prompt exactly where we need it.
In our new command prompt, type in the following before hitting return:
ruby dk.rb init
This creates a file in your
devkit folder called
config.yml which will contain the location of your Ruby installation. Next, type in the following before hitting return:
ruby dk.rb install
This will complete the Ruby Development Kit installation and ou should see output like the image below. You don’t need to worry about the Ruby DevKit again. Once it’s installed, that’s it.
Installing Bundler and other gems
Now we need to 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 (press the windows button on your keyboard, type in
cmd then hit return if you’ve already closed your last one), 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 command prompt, 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 Explorer (press the Windows key and E simultaneously) and navigate to where you want to create your cucumber project. Personally, I always create a ‘code’ folder in my C:/ drive, 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
Installing Sublime Text 2 and creating a Gemfile to install multiple gems
For this, we will need a text editor. You can use Notepad (which comes built into Windows) but 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 http://www.sublimetext.com/ and click the ‘Download for Windows’ button then select to run it. During the installation, be sure to select the checkbox for adding Sublime Text to the Explorer context menu. This just means that once it’s installed you’ll be able to search for it with the Windows button. It’s the only checkbox in the installation so you shouldn’t have trouble spotting 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:
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 command prompt and start to use Bundler. Go back to your command prompt 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 just means change directory. Now we will use Bundler. It’s very easy. In your command prompt 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 http://packagecontrol.io 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 ‘ctrl’, ‘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 command prompt 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.
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.
Ricardo Moreira | 31st October 2015 at 12:29 pm
Thank you very much for the detailed and usefull information tutorial. Congratulations to your nice looking page as well!
Chris Wheatley | 09th July 2015 at 11:52 am
Very detailed step by step instructions, just what I need. I’ll be reading your other articles for sure!
parad1gm | 29th July 2015 at 7:48 pm
I hope it helped. Shout if you need anything else.