0
# Pickle Compilation
1

2
Transforms parsed Gherkin AST into executable test scenarios ("pickles") with scenario outline expansion, tag inheritance, and step processing. The compiler handles complex scenario outline tables and creates individual test cases for each data row.
3

4
## Capabilities
5

6
### Compiler Class
7

8
Main compiler that converts Gherkin documents into executable pickles with scenario expansion and tag processing.
9

10
```python { .api }
11
class Compiler:
12
    def __init__(self, id_generator: IdGenerator | None = None) -> None:
13
        """
14
        Create compiler instance with optional ID generator.
15
        
16
        Parameters:
17
        - id_generator: Optional ID generator for unique test IDs, defaults to IdGenerator()
18
        """
19
        
20
    def compile(self, gherkin_document: GherkinDocumentWithURI) -> list[Pickle]:
21
        """
22
        Compile Gherkin document into executable pickles.
23
        
24
        Parameters:
25
        - gherkin_document: Parsed Gherkin document with URI
26
        
27
        Returns:
28
        - list[Pickle]: List of executable test scenarios
29
        """
30
        
31
    id_generator: IdGenerator
32
    """ID generator for creating unique identifiers"""
33
```
34

35
### Pickle Structure
36

37
Executable test scenario with expanded steps and metadata.
38

39
```python { .api }
40
class Pickle(TypedDict):
41
    astNodeIds: list[str]
42
    """AST node IDs that generated this pickle"""
43
    
44
    id: str
45
    """Unique pickle identifier"""
46
    
47
    tags: list[PickleTag]
48
    """Inherited and direct tags"""
49
    
50
    name: str
51
    """Scenario name (with variable substitution for outlines)"""
52
    
53
    language: str
54
    """Language dialect used"""
55
    
56
    steps: list[PickleStep]
57
    """Executable steps with expanded arguments"""
58
    
59
    uri: str
60
    """Source file URI"""
61

62
class PickleStep(TypedDict):
63
    astNodeIds: list[str]
64
    """Source AST node IDs"""
65
    
66
    id: str
67
    """Unique step identifier"""
68
    
69
    type: str
70
    """Step type: Given, When, Then, Conjunction"""
71
    
72
    text: str
73
    """Step text (with variable substitution)"""
74
    
75
    argument: NotRequired[PickleArgumentEnvelope]
76
    """Optional step argument (DataTable or DocString)"""
77

78
class PickleTag(TypedDict):
79
    astNodeId: str
80
    """Source tag AST node ID"""
81
    
82
    name: str
83
    """Tag name including @ symbol"""
84
```
85

86
### Step Arguments
87

88
Compiled step arguments for data tables and doc strings with variable expansion.
89

90
```python { .api }
91
class PickleArgumentDataTable(TypedDict):
92
    rows: list[PickleArgumentDataTableRow]
93
    """Table rows with expanded cell values"""
94

95
class PickleArgumentDataTableRow(TypedDict):
96
    cells: list[PickleArgumentDataTableCell]
97
    """Row cells with substituted values"""
98

99
class PickleArgumentDataTableCell(TypedDict):
100
    value: str
101
    """Cell value with variables expanded"""
102

103
class PickleArgumentDocString(TypedDict):
104
    content: str | None
105
    """Doc string content with variables expanded"""
106
    
107
    mediaType: NotRequired[str | None]
108
    """Optional media type with variables expanded"""
109
```
110

111
## Usage Examples
112

113
### Basic Compilation
114

115
```python
116
from gherkin import Parser, Compiler
117
from gherkin.stream.id_generator import IdGenerator
118

119
# Parse and compile
120
parser = Parser()
121
compiler = Compiler(IdGenerator())
122

123
gherkin_text = """
124
Feature: Login
125
  @smoke
126
  Scenario: Valid login
127
    Given a user exists
128
    When they enter valid credentials
129
    Then they should be logged in
130
"""
131

132
document = parser.parse(gherkin_text)
133
document_with_uri = {**document, "uri": "features/login.feature"}
134
pickles = compiler.compile(document_with_uri)
135

136
# Process executable scenarios
137
for pickle in pickles:
138
    print(f"Scenario: {pickle['name']}")
139
    print(f"Tags: {[tag['name'] for tag in pickle['tags']]}")
140
    print(f"Steps: {len(pickle['steps'])}")
141
```
142

143
### Scenario Outline Expansion
144

145
```python
146
gherkin_outline = """
147
Feature: Calculator
148
  Scenario Outline: Addition
149
    Given I have <first> and <second>
150
    When I add them
151
    Then I get <result>
152
    
153
    Examples:
154
      | first | second | result |
155
      | 2     | 3      | 5      |
156
      | 5     | 7      | 12     |
157
"""
158

159
document = parser.parse(gherkin_outline)
160
document_with_uri = {**document, "uri": "calc.feature"}
161
pickles = compiler.compile(document_with_uri)
162

163
print(f"Generated {len(pickles)} test scenarios")
164
for pickle in pickles:
165
    print(f"Scenario: {pickle['name']}")
166
    for step in pickle['steps']:
167
        print(f"  {step['type']}: {step['text']}")
168
    print()
169
```
170

171
### Tag Inheritance
172

173
```python
174
gherkin_with_tags = """
175
@feature-tag
176
Feature: User Management
177
  
178
  @background-setup
179
  Background:
180
    Given the system is initialized
181
  
182
  @smoke @priority-high
183
  Scenario: Create user
184
    When I create a new user
185
    Then the user should exist
186
    
187
  @rule-tag
188
  Rule: User validation
189
    
190
    @validation
191
    Scenario: Invalid email
192
      When I create user with invalid email
193
      Then I should get validation error
194
"""
195

196
document = parser.parse(gherkin_with_tags)
197
document_with_uri = {**document, "uri": "users.feature"}
198
pickles = compiler.compile(document_with_uri)
199

200
for pickle in pickles:
201
    print(f"Scenario: {pickle['name']}")
202
    tags = [tag['name'] for tag in pickle['tags']]
203
    print(f"  All tags: {tags}")
204
```
205

206
### Complex Data Tables
207

208
```python
209
gherkin_with_table = """
210
Feature: User Registration
211
  Scenario: Register multiple users
212
    Given the following users:
213
      | name     | email              | role  |
214
      | Alice    | alice@example.com  | admin |
215
      | Bob      | bob@example.com    | user  |
216
    When I register them
217
    Then they should all exist
218
"""
219

220
document = parser.parse(gherkin_with_table)
221
document_with_uri = {**document, "uri": "registration.feature"}
222
pickles = compiler.compile(document_with_uri)
223

224
pickle = pickles[0]
225
step_with_table = pickle['steps'][0]
226
if 'argument' in step_with_table:
227
    data_table = step_with_table['argument']['dataTable']
228
    print("Data table rows:")
229
    for row in data_table['rows']:
230
        values = [cell['value'] for cell in row['cells']]
231
        print(f"  {values}")
232
```
233

234
### Doc String Arguments
235

236
```python
237
gherkin_with_docstring = """
238
Feature: API Testing
239
  Scenario: Send JSON request
240
    Given I prepare a request
241
    When I send the following JSON:
242
      \"\"\"json
243
      {
244
        "username": "testuser",
245
        "password": "secret123"
246
      }
247
      \"\"\"
248
    Then I should get a response
249
"""
250

251
document = parser.parse(gherkin_with_docstring)
252
document_with_uri = {**document, "uri": "api.feature"}
253
pickles = compiler.compile(document_with_uri)
254

255
pickle = pickles[0]
256
step_with_docstring = pickle['steps'][1]
257
if 'argument' in step_with_docstring:
258
    doc_string = step_with_docstring['argument']['docString']
259
    print(f"Doc string content: {doc_string['content']}")
260
    print(f"Media type: {doc_string.get('mediaType', 'text')}")
261
```