Godot Cucumber is an addon for Godot 4.7 that adds Gherkin *.feature files to the editor and lets you execute them as tests.

It is not a full Cucumber port. The addon imports features as resources, opens them in a dedicated editor, parses scenarios, and resolves step definitions you write in GDScript. Pair it with GdUnit4 to run those scenarios as parameterized tests.

Features #

Editor support #

.feature files show up in the FileSystem dock with a cucumber icon. Double-click one to open the Cucumber main screen: a file list on the left, a New button, and a code editor that follows your Godot text editor settings.

Gherkin highlighting #

Keywords, tags, comments, strings, and numbers use the same colors as the script editor.

Steps you write in GDScript #

Extend CucumberSteps, register Given / When / Then expressions, and map them to callbacks. Placeholders such as {int}, {float}, {string}, and {word} become typed arguments.

GdUnit4 runner #

CucumberTest discovers every scenario in a folder and runs each one as a parameterized test. Failures point at the feature path and line.

Installation #

1. Copy addons/cucumber into your project's addons folder.
2. Enable the plugin: Project > Project Settings > Plugins.
3. To run feature scenarios as tests, also enable GdUnit4.

Godot version:

Godot	Cucumber
4.7	1.x

Getting started #

A feature describes behavior in English. A step definition is the GDScript that makes that line do something.

@hello
Feature: Greeting
  Background:
    Given the hello scene is running

  Scenario: Greet the world
    When the scene greets "World"
    Then the scene message is "Hello, World!"
    And the scene greeting count is 1

Create a new file from the Cucumber tab, or drop an existing .feature onto the editor. The parser currently understands:

• Feature, Background, and Scenario
• Given, When, Then, and And
• feature and scenario tags
• {int}, {float}, {string}, and {word} in step expressions

Register the matching steps:

extends CucumberSteps


func define_steps() -> void:
	when({
		"expression": "the scene greets {string}",
		"callback": _when_scene_greets,
	})


func _when_scene_greets(payload: Dictionary) -> void:
	payload.context.state.scene.greet({"name": payload.arguments[0]})

Then expose the folder to GdUnit4:

extends CucumberTest


func feature_directory() -> String:
	return "res://features"


func step_definitions() -> Array[CucumberSteps]:
	return [HelloSteps.new()]


func test_feature(
		scenario: Dictionary,
		_test_parameters := feature_cases()
) -> void:
	await execute_scenario(scenario)

This repository includes features/hello.feature and demo/hello_scene.tscn so you can see a working suite.

Run tests #

Install Godot 4.7, then:

./run_tests.sh

If Godot is not on PATH:

GODOT_BIN=/path/to/godot ./run_tests.sh

The Tangled workflow in .tangled/workflows/test.yml runs the same suite on push.

Layout #

• addons/cucumber is the addon: importer, editor, parser, step registry, and CucumberSteps.
• features/ and demo/ are a sample suite used to develop the addon.
• test/cucumber_test.gd is the GdUnit runner you can copy into your own project.
• test/steps/ maps the sample feature lines to Godot code.

License #

MIT. See LICENSE.

Credits #

• cucumber icon from Material Icon Theme (MIT). See addons/cucumber/ICON-LICENSE.md.
• tests run on GdUnit4.