0
# Cucumber-Java
1

2
Cucumber-Java provides annotation-based step definitions for Behavior-Driven Development (BDD) testing within the Cucumber framework. It enables developers to write automated tests in plain language that can be read by both technical and non-technical team members, improving communication and collaboration in software development teams.
3

4
## Package Information
5

6
- **Package Name**: cucumber-java
7
- **Package Type**: Maven
8
- **Group ID**: io.cucumber
9
- **Artifact ID**: cucumber-java
10
- **Language**: Java
11
- **Installation**: Add dependency to pom.xml:
12

13
```xml
14
<dependency>
15
    <groupId>io.cucumber</groupId>
16
    <artifactId>cucumber-java</artifactId>
17
    <version>7.22.1</version>
18
    <scope>test</scope>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
import io.cucumber.java.en.*;
26
import io.cucumber.java.Before;
27
import io.cucumber.java.After;
28
import io.cucumber.java.Scenario;
29
import io.cucumber.java.PendingException;
30
import io.cucumber.java.ParameterType;
31
import io.cucumber.java.DataTableType;
32
import io.cucumber.java.DocStringType;
33
```
34

35
For other languages (internationalization):
36

37
```java
38
import io.cucumber.java.fr.*;  // French
39
import io.cucumber.java.de.*;  // German
40
import io.cucumber.java.es.*;  // Spanish
41
// 70+ other language packages available
42
```
43

44
## Basic Usage
45

46
```java
47
package com.example.stepdefs;
48

49
import io.cucumber.java.en.*;
50
import io.cucumber.java.Before;
51
import io.cucumber.java.After;
52
import io.cucumber.java.Scenario;
53

54
public class CalculatorStepDefinitions {
55
    private Calculator calc;
56

57
    @Before
58
    public void setUp() {
59
        calc = new Calculator();
60
    }
61

62
    @Given("a calculator I just turned on")
63
    public void a_calculator_I_just_turned_on() {
64
        // Calculator already initialized in setUp
65
    }
66

67
    @When("I add {int} and {int}")
68
    public void adding(int arg1, int arg2) {
69
        calc.push(arg1);
70
        calc.push(arg2);
71
        calc.push("+");
72
    }
73

74
    @Then("the result is {int}")
75
    public void the_result_is(int expected) {
76
        assertEquals(expected, calc.value());
77
    }
78

79
    @After
80
    public void tearDown(Scenario scenario) {
81
        if (scenario.isFailed()) {
82
            scenario.log("Test failed: " + scenario.getName());
83
        }
84
    }
85
}
86
```
87

88
## Architecture
89

90
Cucumber-Java is built around several key architectural components:
91

92
- **Step Definition Annotations**: Language-specific annotations (`@Given`, `@When`, `@Then`) generated for 70+ languages
93
- **Hook System**: Lifecycle management with `@Before`, `@After`, `@BeforeAll`, `@AfterAll`, `@BeforeStep`, `@AfterStep`
94
- **Parameter Transformation**: Custom parameter types with `@ParameterType` and default transformers
95
- **Data Handling**: Built-in support for data tables and doc strings with custom transformations
96
- **Runtime Context**: `Scenario` object provides access to test execution context and reporting
97
- **Internationalization**: Code generation system creates localized step definition annotations
98

99
## Capabilities
100

101
### Step Definitions
102

103
Core step definition annotations for writing BDD test steps in multiple languages. Supports both Cucumber expressions and regular expressions.
104

105
```java { .api }
106
// English annotations (most commonly used)
107
@Given("step text with {parameter}")
108
@When("step text with {parameter}")
109
@Then("step text with {parameter}")
110
@And("step text with {parameter}")
111
@But("step text with {parameter}")
112
```
113

114
[Step Definitions](./step-definitions.md)
115

116
### Lifecycle Hooks
117

118
Comprehensive hook system for test setup, teardown, and step-level interception across different scopes.
119

120
```java { .api }
121
@Before("@tag-expression")
122
public void setUp(Scenario scenario) { }
123

124
@After(order = 1000)
125
public void tearDown(Scenario scenario) { }
126

127
@BeforeAll  // EXPERIMENTAL
128
public static void beforeAll() { }
129

130
@AfterAll   // EXPERIMENTAL
131
public static void afterAll() { }
132
```
133

134
[Lifecycle Hooks](./hooks.md)
135

136
### Parameter Transformation
137

138
Custom parameter types for converting step parameters from strings to domain objects, with extensive configuration options.
139

140
```java { .api }
141
@ParameterType("\\d{4}-\\d{2}-\\d{2}")
142
public LocalDate date(String dateString) {
143
    return LocalDate.parse(dateString);
144
}
145

146
@DefaultParameterTransformer
147
public Object defaultTransformer(String fromValue, Type toValueType) {
148
    // Custom transformation logic
149
    return transformed;
150
}
151
```
152

153
[Parameter Transformation](./parameter-transformation.md)
154

155
### Data Handling
156

157
Robust data table and doc string handling with custom transformations and built-in collection support.
158

159
```java { .api }
160
@DataTableType
161
public Person personEntry(Map<String, String> entry) {
162
    return new Person(entry.get("name"), entry.get("email"));
163
}
164

165
@DocStringType
166
public JsonNode json(String docString) {
167
    return objectMapper.readTree(docString);
168
}
169
```
170

171
[Data Handling](./data-handling.md)
172

173
### Runtime Context
174

175
Access to scenario information, status, and reporting capabilities during test execution.
176

177
```java { .api }
178
public class Scenario {
179
    Collection<String> getSourceTagNames();
180
    Status getStatus();
181
    boolean isFailed();
182
    void attach(byte[] data, String mediaType, String name);
183
    void attach(String data, String mediaType, String name);
184
    void log(String text);
185
    String getName();
186
    String getId();
187
    URI getUri();
188
    Integer getLine();
189
}
190

191
public enum Status {
192
    PASSED, SKIPPED, PENDING, UNDEFINED, AMBIGUOUS, FAILED, UNUSED
193
}
194
```
195

196
[Runtime Context](./runtime-context.md)
197

198
## Types
199

200
```java { .api }
201
// Core exception for marking unimplemented steps
202
public final class PendingException extends RuntimeException {
203
    public PendingException();
204
    public PendingException(String message);
205
}
206

207
// Annotation for transposing data tables (used on parameters)
208
public void stepWithTransposedTable(@Transpose DataTable table) { }
209

210
// Meta-annotations for step definitions (internal use)
211
@StepDefinitionAnnotation
212
@StepDefinitionAnnotations
213
```