cucumber-ruby: plain-language tests for Ruby teams

What cucumber-ruby actually solves

The README states the goal plainly: Cucumber runs automated tests written in plain language, so they can be read by anyone on the team, and that readability is meant to improve communication and trust. The Ruby implementation is one of several; the README points to JavaScript, Java and a longer list at cucumber.io/docs/installation. The audience is therefore a Ruby project that wants its acceptance criteria stored in files that a product manager or support engineer can open without a Ruby environment. That is a narrower claim than "better tests". The value is in the shared artifact, not in the assertion library underneath, which is whatever you already use in Ruby. If nobody outside the engineering team will ever read the feature files, the plain-language layer is overhead you are paying for and not collecting on.

How a feature file becomes a passing or failing run

Three pieces cooperate. A .feature file holds Gherkin: a Feature, optionally a Rule, and one or more Example blocks whose lines begin with Given, When and Then. Those lines are not code. They are matched at runtime against step definitions written in Ruby, registered with the Given, When and Then methods. The README's own sample registers Given('this will pass'), Given('this will fail'), When('I do an action') and Then('some results should be there'), and the last one calls expect(@this_will_pass).to be true. The instance variables set in one step are visible in later steps of the same example, which is how state moves through a scenario. The runner loads features and features/step_definitions, resolves each Gherkin line to a block, and reports per-example results. Anything you want to assert with comes from the surrounding Ruby project; the README's example uses expect and be, so an RSpec-style matcher is in play, but Cucumber itself only supplies the matching and the run.

Installing the gem and running a first feature

Cucumber for Ruby is a gem. The README gives two routes: add `gem 'cucumber'` to your Gemfile and run `bundle`, or install it directly. The README then assumes bundler and prefixes every command with `bundle exec`, noting that without bundler you call `cucumber` directly. Supported platforms listed are Ruby 4.0, 3.4, 3.3 and 3.2, TruffleRuby 24.0.0+ and JRuby 10.0+, with JRuby carrying documented limitations in docs/jruby-limitations.md.

gem install cucumber

If you use bundler instead, the Gemfile line and the install step are:

bundle

Before writing anything, scaffold the directory. The README says this creates features, features/step_definitions and features/support/env.rb if they do not already exist, and prints the tree it produced.

bundle exec cucumber --init

Now add a feature file. The README's example is a Feature named Rule Sample containing a Rule with two Example blocks, one expected to pass and one to fail.

# features/rule.feature
Feature: Rule Sample

  Rule: This is a rule

    Example: A passing example
      Given this will pass
      When I do an action
      Then some results should be there

Step definitions go in features/step_definitions. The README's file defines four steps and ends with an expectation on an instance variable set earlier in the scenario.

# features/step_definitions/steps.rb
Given('this will pass') do
  @this_will_pass = true
end

Then("some results should be there") do
  expect(@this_will_pass).to be true
end

Run everything, or narrow the run. A path alone runs one feature file; appending a colon and a line number runs the example whose name sits on that line.

bundle exec cucumber
bundle exec cucumber features/rule.feature:5

For a summary on standard output plus an HTML file on disk, the README gives this combination of --format, --out and a filename. You should end up with report.html written next to your project.

bundle exec cucumber --format summary --format html --out report.html

`bundle exec cucumber --help` lists the rest, and the repository keeps CLI documentation under features/docs/cli.

Where the plain-language layer turns into maintenance

Step definitions are global string matches. Every Gherkin line in every feature file is resolved against the same pool of registered blocks, so two teams writing similar sentences in one repository will collide or, worse, silently share a step whose implementation only suits one of them. The README's sample sidesteps this by using throwaway sentences like 'I do an action', which is fine for a tutorial and useless as a naming policy. There is no scoping mechanism described in the README for limiting a step to one feature file. The practical consequence is that step wording becomes an interface you have to govern, and rewording a sentence means finding every feature file that used the old one. A second limitation is that the runner is not a browser driver. Nothing in the README automates a UI; the step bodies have to call whatever library you choose. Teams that expect Cucumber to click buttons will be disappointed, and the related searches for Cucumber Playwright point at the pairing people actually make rather than at anything built in. Finally, the README does not document rollback or migration steps between major versions. The repository does carry an upgrading_notes directory and a CHANGELOG.md, and those are where you look before moving across a major release, but the README itself is silent on the subject.

cucumber-ruby against RSpec and Minitest

RSpec and Minitest are the obvious alternatives, and the difference is not the assertions. All three end up calling expect or assert inside Ruby. The difference is the layer above. In RSpec you write describe and it blocks in Ruby and the description strings are comments as far as execution is concerned; nothing outside the file can key off them. In cucumber-ruby the Gherkin line is the key. That line is matched against step definitions at runtime, which means the specification can be edited by someone who does not write Ruby, and it also means an unmatched line is a hard failure rather than a cosmetic string. You are trading a Ruby-only editing surface for a two-file editing surface: change the sentence in the .feature file, then change or add the matching step. The other real difference is granularity. RSpec is built for unit-level isolation; cucumber-ruby's examples read as end-to-end journeys through a system, which is the shape the README's Given/When/Then sample has. If your tests are mostly single-method checks, RSpec is the shorter path and cucumber-ruby adds a translation layer with no reader on the other side of it.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-22. Releases are frequent enough to matter: v11.0.0 on 2026-04-14, v11.1.0 on 2026-06-01 and v11.1.1 on 2026-06-25. A major version landing in April and two minor releases inside the following three months is a normal cadence for a mature project, and it also means your Gemfile constraint deserves attention. Pinning to the pessimistic operator on a minor version keeps you inside a line that may receive patches; floating across a major boundary means reading upgrading_notes and CHANGELOG.md before you run anything. The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the gem, but the LICENSE file is the authoritative text and this is not legal advice. One cost that does not show up in a changelog: because step definitions are project-wide, a major upgrade that changes matching or reporting behaviour can require edits scattered across your features directory rather than in one file. Budget for that when you decide how tightly to pin.

Editorial conclusion

Adopt cucumber-ruby if your team already writes Ruby and wants acceptance criteria that non-programmers can read, and if you are prepared to maintain the step definitions that connect those sentences to code. Do not adopt it as a general unit test runner or as a browser driver; it delegates that work. Before committing, verify one thing: run bundle exec cucumber --init in a scratch directory and then bundle exec cucumber --format summary --format html --out report.html on a real feature to confirm the two report formats you plan to consume actually produce files you can read.

Frequently asked questions

Official sources

1. cucumber/cucumber-ruby on GitHub
2. License: MIT
3. Project website
4. README
5. Releases