June 18, 2018

Intro to setting up a BDD framework with VS Code + Gauge + Ruby

With Integrated Development Environments (IDE), I am quick to adopt whatever the rest of the developers on the team use. For Java development, I like IntelliJ IDEA Ultimate Edition. For JavaScript, Atom.io. And for writing the Capybara + Ruby framework, I have also been using Atom. The problem is that the BDD framework we are using at work -- Gauge -- has plugins that help refactor Gauge tests written in Java, but hasn't had anything for refactoring Gauge tests written in Ruby... until now.

With this blog article, I will be investigating Visual Studio Code -- commonly known as VS Code -- and how it helps refactor tests.

Why am I currently using Ruby for my automation framework if the BDD Framework hasn't supported it? Both Chef.io -- what I use to spin up virtual environments -- and GitLab.com -- the code storage / continuous integration environment also uses Ruby.

I've written a bit about Gauge and drafted a quick-and-dirty Gauge + Ruby + Selenium project, on this blog. With this experiment, we will be editing Gauge's built in project, setting up everything on my Windows 10 machine at home.

If you want to view a summary what the gauge-vscode can do, view the official docs on GitHub.

Setting Up VS Code + Ruby + Gauge

Setting up Ruby:

  • To set up the Ruby programming language on a Windows environment, follow the directions on RubyInstaller.org.
  • Note, there are many ways of installing Ruby. Here are a few examples.
  • Make sure to install the bundler gem from Bundle.iogem install bundler

Using Windows? Install Chocolatey:

  • Open the Command Prompt as Administrator
  • Follow instructions for  Install Chocolatey.org, the Windows Package Manager, copying the command text, and pasting it in the Windows command shell. 
  • Close and reopen your command prompt, running, again, as an administrator. 
Install Gauge:
  • Follow the prompts for installing Gauge at https://gauge.org/get-started.html
  • Once you have Chocolatey installed, it is: choco install gauge
  • Is gauge working? Type: gauge -v
Create New Gauge-Ruby project:
  • Create the subfolder where you want to keep the project. For this project, I went to C:\Users\tmaher\ and created a new folder, gauge-ruby. Enter the subfolder.
  • Initialize a new Gauge-Ruby project: gauge init ruby. 
  • After all project dependencies are downloaded and installed from Rubygems.org, make sure you can run the test project: bundle exec gauge run specs/
  • Want to see exactly what is happening? Run the project in verbose mode with -v: bundle exec gauge run specs/ -v
  • Are updates available?: gauge-update ruby
As you can see below, the sample project tallies up vowels "aeiou" (leaving out 'y'), in words such as "Gauge", "Mingle", "Snap", etc.

Output of the Gauge Sample Project.
... If you want to see what the code is doing, and don't feel like setting up a project, you can check out the code produced in the Gauge 0.9.7 project on my GitHub site

Setting up VS Code:

  • Downloads for Windows, Mac, or Linux is on the Code.VisualStudio.com Downloads page. 
  • VS Code wanted me to immediately wanted me to Download Git. I had uninstalled it since I wanted to upgrade to the new version. It provided a handy link to download, and I could set up VS Code as an editor. 
Install the Ruby plugin:
  • The Welcome page displayed a Customize widget that I was able to click in order to see the Exentions: Marketplace. I was able to scroll down to "Ruby" and click to install it. This is from Rubyide's vscode-ruby project. Like Atom.io, VS Code seems fast, lightweight, and able to be customized with various plugins. 
Welcome to VS Code!
Install the VS Code Gauge Plugin:

  • See the square thingy on the bottom? Hover your cursor over it, and it should tell you that it is Extensions. Select that, and search for the keyword "gauge". Select to install it. 

VS Code Welcome Screen

Now that we have everything set up, let's give everything a whirl!

  • Open up VS Code
  • Select File -> Open Folder, and open up your project. Mine was in C:\Users\tmaher\gauge-ruby
What a nice touch, ThoughtWorks! To help get us started, we are presented with a new dashboard. 

The Gauge Dashboard
  • Apply & Reload recommended changes. Add a workspace folder by going to File -> Add Folder to Workspace
  • Open the Command Palette: In VS Code, select View -> Command Palette, type in "Gauge" then select Gauge: Welcome, to go back to the Welcome screen.   
On the Welcome Screen, it provides:
  • Ways to learn the Gauge toolset by providing links to help you learn the Gauge terminologies, and how Gauge uses Markdown.
  • "Run All Specifications" runs the tests from inside VS Code. 
  • How to Report an Issue, Ask a Qustion, Chat, or go the the Google Group forum. 

Running Gauge Tests in VS Code

  • From UI: Opening the Command Palette, typing in "Gauge" and selecting "Gauge: Run All Specifications". You may need to raise the output panel to see the results. By default it only showed one or two lines of output. 
  • From Terminal: On the panel at the bottom, listing Problems, Output, Debug Console, and Terminal, select the Terminal tab. This will show either the Windows PowerShell or the Mac Terminal. Enter: bundle exec gauge run specs/

View Reports
  • Want to see reports? Select where it says "Successfully generated html-report", and it will output the location to the command line. Go there, press the Enter key, and the reports will be entered into your browser. 

I highly advise you to get used to executing things through the Terminal in VS Code, especially if you are used to Windows environments, like I am. The main thing that had been holding me back in my automation development career had been my fear of using the command line. It's easier. It's quicker. And it will get you working in the same way the software developers on your team are working. 

Finding Previously Defined Steps

Let's say you defined a step:

 step 'Vowels in English language are <vowels>.' do |vowels|  
  @vowels = vowels.scan(/./)  

This readable step, full of detail, can be hard to remember, when trying to implement it in a spec file.

If we open up the spec file, specs/example.specs, from the very moment we type a bullet point to add a new step, a popup is displayed showing all the previously designed steps. Enter a few more words, such as "language" and it will filter down to the step "Vowels in English language are..." 

Previously defined specs are shown

Rephrase Test Steps

Gauge uses Markdown as a theme to write tests. Each specification has a heading. Each scenario has a subheading. And each step is captured as a bullet point, which corresponds to a step implementation. 

When a test is executing, the spec takes the language of the step and attempts to match it to a phrase in the step implementation. What happens if you want to make changes to the wording? If you do not find all areas in the specs that match the step definition, things will start failing. 

What if we wanted to rephrase the step definition "The word <word> has <count> vowels." to read as: "There are <count> vowels in the word <word>"?

We could easily do it through the command line! Just like on the command line, we could go to the Terminal and type in:

gauge refactor "The word <word> has <count> vowels." "There are <count> vowels in the word <word>"

... This is a really nice start on a much needed plugin. I hope they come up with one for IntelliJ IDEA + Ruby and RubyMine!

Happy Testing!

-T.J. Maher
Sr. QA Engineer, Software Engineer in Test
Meetup Organizer, Ministry of Testing - Boston

Twitter | YouTube | LinkedIn | Articles