Cucumber Project/folder Structure


In all the three tutorials i.e. Basic, Intermediate and Advanced, we have used cucumber project template and used it and wrote our scenarios. However we never got a chance to talk about the overall project structure and why a certain file/folder exists the way it is structured. Obviously there is some convention (meaning a rule is defined) and there is some configuration (flexibility to modify some rules through configuration). In this post we will first talk about the folder structure we adopted all through the tutorials and set a stage, so that we don’t have to worry one fine day – Hmm, what is the purpose of this Rakefile for example? 😉

Cucumber Project structure:

Compared to other programming languages, Ruby is generally readable and easier and so the folder structure is also less authoritative, though a very noteworthy observation not to miss before we go into frameworks discussion. Below is a high level illustration. I will explain below in addition to the call outs.


  1. features folder is where we write all .feature files i.e. Cucumber features and scenario – describe the behavior of application in .feature files
  2. features folder also contains step_definitions folder – this is where all the glue code , otherwise automation code which we have been writing so far goes into .rb files
  3. features folder also contains support folder – we will explain in detail below
  4. At the project root, cucumber.yml contains all the configuration options that cucumber parser understands is present. It contains options like html reports, environment variables (parameterizing browser, archiving results etc)
  5. Gemfile contains all the gems that are used in this project and manged by bundler
  6. Gemfile.lock contains the exact versions of the gems when bundler ran last. There are pros and cons of checking this file into source code repository, but thats for a later discussion. For now bundler install/update will re-generate this file whenever you want to
  7. LICENSE.txt contains license information for this project
  8. Rakefile contains the rake tasks that we will eventually use on CI server
  9. contains all the read me information for this project and is formatted well on github
  10. results.html gets generated when we run cucumber with html reports on.

Support folder:


When Cucumber is run, there is a certain sequence of events that happen before the actual scenario is run. All ruby code under support folder gets loaded into the ruby runtime context. Hence we would want to load up all gems and their modules in the env.rb file as below for example.

It is important to note here that we can externalize any ruby code and then include it in context, by using env.rb file. For example, I can have my ruby files in a completely different folder, however if I intend to use them, then I have to include it in env.rb. When we discuss frameworks in details,we will talk about re-usability and how we can keep ruby code in separate folder and include those modules/classes into the current project and some other cucumber project too.


Similarly, hooks.rb also gets loaded. We will discuss advanced options for hooks.rb when we talk about Cucumber hooks in a separate post. Think of hooks.rb as pre-condition and post-condition activities for test cases. We do this with Before and After block as follows for example: