Skip to content
A gem that lets you focus on your Cucumber acceptance tests, and not worry about configuring the drivers
Branch: master
Clone or download
Cruikshanks Fix issue with always running parallel (#93)
Found when using Quke that even if parallel was disabled it would always run parallel anyway even if `--single` had been passed in to ParallelTests.

After some testing found it was because we would still set `--group-by`. It must be that if this is set ParallelTests defaults back to attempting to run in parallel and ignores the `--single` argument.

Hence this change which now only sets `--group-by` if parallel is enabled in the config.
Latest commit 86088fb Mar 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Fix issue with always running parallel (#93) Mar 15, 2019
.rspec Initial conversion of Quke to a gem Oct 4, 2016
LICENSE Use cucumber --fast-fail to stop on error (#90) Mar 1, 2019
Rakefile Update project to match latest CI conventions (#76) Feb 26, 2019
quke.gemspec Add support for running tests in parallel (#83) Feb 28, 2019
quke.png Initial conversion of Quke to a gem Oct 4, 2016

Quke logo

Build Status Maintainability Test Coverage security Gem Version Licence

Quke is a gem that helps you to build a suite of Cucumber acceptance tests.

Quke tries to simplify the process of writing and running these tests by setting up Cucumber for you. It handles the config to allow you to run them in Firefox (via Selenium) and Chrome (via Selenium), or the headless browser PhantomJS (via Poltergeist). It also has out of the box support for using Browserstack automate. This leaves you to focus on just your tests.

It was born out of trying to make the process for team members without a development background as simple as possible, and to get them involved in writing and building acceptance tests that they then manage.

It also includes the ability to run those tests using Browserstack. Browserstack gives you the ability to test your application with different combinations of platform, OS, and browser all in the cloud.


You'll need Ruby installed (ideally the latest version available) plus the Bundler gem.

The only other dependency this project has is the browsers you intend to use it with. It is currently setup to work with

The one you may not have heard of is PhantomJS. It is a headless browser.

A headless browser is a web browser without a graphical user interface

Quke uses PhantomJS as its default browser. Using a headless browser the tests will run much faster and means Quke can also be used as part of your CI build.

It is assumed you know what Chrome and Firefox are and how to install them.

Install PhantomJS


We highly recommend using Homebrew if you are using a Mac for installing packages like PhantomJS.

Once installed run brew install phantomjs


You'll need to


Add this line to your application's Gemfile

gem 'quke'

And then execute:

$ bundle

Or install it yourself as

$ gem install quke


You can configure Quke using a .config.yml file. What can be configured essentially falls into one of 3 groups.

  • Quke configuration - things like which driver to use, whether to pause between steps, or if Quke should stop in the event of an error
  • Custom configuration - add your own custom values using the custom: node
  • Browserstack configuration - specify exactly how you want your Browserstack session to run, for example which browser and OS to test against, the project name, and your credentials.

See .config.example.yml for full details of the options you can specify in your .config.yml.

Multiple configs

When Quke runs it will default to looking for .config.yml. However you can override this and tell Quke which one to use. This allows you to create multiple config files.

You do this using an environment variable. The most flexible way is to set the variable as part of your command.

QUKE_CONFIG='chrome.config.yml' bundle exec quke

The use case is to allow you to have different configs setup ready to go, and enable you to switch between them. For example when testing with Chrome and Firefox you set a 1 second delay between steps so you can observe the tests as they run through, but in your default .config.yml you want no pauses and use phantomjs.


If you are testing a site that requires some form of login, or you are using Browserstack you'll need to tell Quke about the credentials. Generally we advise not committing your .config.yml to source control, but we understand you may well build up a suite of them that you want to store with the project and share with others.

If that's the case make use of the following features.

Browserstack environment variables

.config.example.yml is an example of a config file which contains username, auth_key, and if local testing local_key. You really don't want these becoming known so if you have to commit the config file, remove them and instead set the following environment variables wherever you need to run the tests.


Quke looks for them when configuring the Browserstack driver and only if not found does it then go looking in the config file.

Ruby's ENV classs

You can access any environment variable from within your project using ENV.

secret_key = ENV['SUPER_SECRET_KEY']

You can set them by calling export SUPER_SECRET_KEY="password123" in your terminal prior to running Quke. In this way for example, the passwords featured in the custom section in .config.example.yml could be removed, and instead your step could read the value it needs to submit from an environment variable.


TODO: Write usage instructions here


You should be aware of some default behaviours included in Quke.

Displaying web pages on fail

Capybara includes the ability to save the source of the current page at any point. Quke has been configured so that if you are not using a headless browser and a step fails it will save the source to file and then use a tool called Launchy to open it in your default browser.

You can disable this behaviour using display_failures: false in your .config.yml

Quit on 5 failures

If you are running using Chrome or Firefox after the 5th failure Quke will automatically stop. This is to prevent scores of tabs being opened in the browser when an error is found and Quke is set to show failures, which may just be the result of an error in the test code.

Automatically setting Browserstack session status

If you are using the Browserstack driver, Quke will automatically update the status of the session recorded in Browserstack for you. If all tests pass, it will be marked as 'passed', else it will be marked as 'failed' (it defaults to 'completed').


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Whilst just developing a gem like Quke you can execute it with

$ ruby -Ilib ./exe/quke

and pass in arguments as well

$ ruby -Ilib ./exe/quke --tags @wip

Contributing to this project

If you have an idea you'd like to contribute please log an issue.

All contributions should be submitted via a pull request.



The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.

You can’t perform that action at this time.