# cucumber-core: The Inner Engine of Ruby Cucumber

> cucumber-core is the inner hexagon of the Ruby Cucumber implementation: a Ruby gem with no user interface that holds the core domain logic for executing Gherkin features. Tool authors and developers building custom Cucumber integrations use its API directly, bypassing the higher-level cucumber gem.

**cucumber/cucumber-ruby-core** — Core library for the Ruby flavour of Cucumber

- Repository: https://github.com/cucumber/cucumber-ruby-core
- Stars: 36 · Forks: 48
- Language: Ruby
- License: MIT
- Published: 2026-08-27 · Updated: 2026-08-27 · Language: en
- Canonical page: https://hysenlabs.com/projects/cucumber-cucumber-ruby-core

## What cucumber-core Is and Who It Is For

The Ruby Cucumber ecosystem separates the core execution logic from the user-facing command-line tool. cucumber-core is that core: a Ruby gem that accepts Gherkin documents and a pipeline of filters, executes the resulting test cases, and reports outcomes back through the same pipeline. It has no CLI, no configuration file format, and no step definition DSL of its own.

The README describes it as the inner hexagon for the Ruby flavour of Cucumber, referring to the hexagonal architecture pattern where the domain logic sits at the centre, isolated from any particular delivery mechanism. The outer layers, such as the cucumber gem that most Ruby teams use, delegate their execution logic to cucumber-core.

The primary audience is developers who are building tools that work with Gherkin documents: custom formatters, IDE plugins, parallel test runners, or any integration that needs to exercise Cucumber features programmatically without the full cucumber gem's overhead. Engineers who just want to write and run Gherkin tests should use the cucumber gem directly.

## Installing cucumber-core

cucumber-core is distributed as a Ruby gem. To add it to a project using Bundler, add the following to the Gemfile:

```ruby
gem 'cucumber-core'
```

Then install with:

```bash
bundle
```

Alternatively, install the gem directly without Bundler:

```bash
gem install cucumber-core
```

The current release is v19.0.0, published on 2026-08-19. The repository also shows v18.0.0 (2026-07-13) and v17.0.0 (2026-06-01) as recent releases, which means a new major version has shipped roughly every six weeks. Each major version increment suggests breaking API changes, so pinning the version in a Gemfile is prudent when building tools against the API.

Supported platforms follow those of the cucumber-ruby repository, which the README points to for the current compatibility matrix.

## How the Execution Pipeline Works

cucumber-core models test execution as a pipeline of filters. Each filter receives test cases and test steps from upstream and passes transformed versions downstream. The README provides an example that illustrates the pattern. A custom filter class inherits from Cucumber::Core::Filter and overrides the test_case method:

```ruby
require 'cucumber/core'
require 'cucumber/core/filter'

class ActivateSteps < Cucumber::Core::Filter.new
  def test_case(test_case)
    test_steps = test_case.test_steps.map do |step|
      step.with_action { print "processing: " }
    end

    test_case.with_steps(test_steps).describe_to(receiver)
  end
end
```

A Gherkin document is wrapped in a Cucumber::Core::Gherkin::Document object. The runner mixes in Cucumber::Core and calls execute with an array of documents and the filter pipeline. Running the example script with ruby cucumber_core_example.rb produces output like:

```bash
ruby cucumber_core_example.rb
```

The README shows the expected output prints each step with a checkmark as each step action fires, confirming the pipeline processed them in order.

The docs/ARCHITECTURE.md file in the repository provides deeper explanation of what the execution pipeline actually does and how to work with it.

## The Gherkin Document Model

Gherkin is the plain-language format Cucumber uses for feature files. A Gherkin document consists of one or more Scenarios grouped under a Feature, with each Scenario made up of Given/When/Then steps. cucumber-core represents these documents internally and provides the domain objects that filters and runners work with.

The README's example constructs a Gherkin document inline as a heredoc:

```ruby
feature = Cucumber::Core::Gherkin::Document.new(__FILE__, <<-GHERKIN)
Feature:
  Scenario:
    Given some requirements
    When we do something
    Then it should pass
GHERKIN
```

In production use, feature files are read from disk and wrapped in the same Document class. The separation of the document model from the execution and reporting layers is what makes it possible to swap the step definition matching and reporting mechanisms without touching the core parsing or execution logic.

The cucumber-gherkin gem handles the actual Gherkin parsing; cucumber-core depends on it. The CONTRIBUTING.md file in the repository documents how to work with local checkouts of cucumber-gherkin and cucumber-messages for developers who need to change parsing behaviour.

## Limitations of Building Directly on cucumber-core

The API breaks frequently. The project ships major version releases roughly every six to eight weeks based on the recent release history. Each major version can introduce incompatible changes to the filter interface, the test case model, or the Gherkin document API. There is no long-term support policy documented in the repository.

This is not a problem for teams using the cucumber gem, which manages its own dependency on cucumber-core and handles the upgrade path. It is a significant concern for developers who build tools directly against cucumber-core, because each major version can break a downstream tool without warning beyond the version bump.

The upgrading_notes/ directory contains notes for migrating between major versions, and the CHANGELOG.md tracks changes. Reviewing both before upgrading a tool that depends on this gem is important.

cucumber-core also has no step definition matching of its own. It defines and executes test cases but delegates step matching entirely to the enclosing tool. A developer building a test runner from scratch must implement their own step definition lookup and binding mechanism, which is non-trivial.

## Maintenance, Licence, and Community

The last push to the repository was on 2026-09-25, and the release cadence shows major versions shipping every six to eight weeks. The project is part of the broader Cucumber organisation and accepts contributions following the process in CONTRIBUTING.md.

The repository is licensed under MIT, which allows use in commercial and open-source projects without restriction. All contributors are expected to follow the Cucumber code of conduct, linked in the README.

Community support is available through the Cucumber Discord server, with an invite link in the README. The Cucumber documentation site at cucumber.io covers the user-facing aspects of writing and running features. For the internal API specifically, docs/ARCHITECTURE.md is the primary reference beyond the code itself.

A notable design choice in the project structure is the separation between the Ruby API (lib/) and the test suite (spec/), which uses RSpec. The .rubocop.yml and .rubocop_todo.yml files show that the project enforces Ruby style checks, though some violations are tracked for future cleanup.

## Conclusion

cucumber-core is the right dependency for developers building custom test runners, IDE integrations, or reporting tools on top of the Cucumber execution model in Ruby. The cucumber gem, which most teams use for writing and running tests, already depends on cucumber-core internally. If you are writing Gherkin features and running them from the command line, use cucumber instead. For v19.0.0, check the upgrading_notes/ directory in the repository before migrating from an earlier major version, as the gem has a history of breaking changes documented there.

## FAQ

### What is Cucumber in Ruby?

Cucumber in Ruby is a testing tool that lets teams write automated tests in plain Gherkin language, which can be read by non-technical stakeholders. cucumber-core is the inner engine that handles Gherkin feature execution, and the cucumber gem provides the full user-facing CLI and step definition DSL built on top of it.

### What is Cucumber Gherkin?

Gherkin is the plain-language format used to write Cucumber feature files. It uses Given/When/Then keywords to structure test scenarios. cucumber-core works with Gherkin documents through the Cucumber::Core::Gherkin::Document class, which wraps a feature file's content for processing by the execution pipeline.

### What is the current version of Cucumber for Ruby?

The current release of cucumber-core is v19.0.0, published on 2026-08-19. The gem follows a rapid major-version release cadence, with v17, v18, and v19 all shipping within a four-month window.

## Sources

- [Official README](https://github.com/cucumber/cucumber-ruby-core#readme)
- [Project repository](https://github.com/cucumber/cucumber-ruby-core)
- [Release notes](https://github.com/cucumber/cucumber-ruby-core/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cucumber-cucumber-ruby-core