BerryCrush VS Code Extension

IDE support for BerryCrush .scenario and .fragment files.

Features

Syntax Highlighting

Full syntax highlighting for BerryCrush scenario DSL:

• Keywords: scenario, feature, given, when, then, and, but
• Directives: call, assert, extract, include, body, bodyFile
• Auto-test: auto:, excludes: for automatic test generation
• Conditionals: if, else if, else with and/or operators
• Operation IDs: ^operationId
• Variables: {{variableName}}, ${variableName}
• Test context: test.type, test.field, test.description, test.value, test.location
• Tags: @smoke, @ignore, etc.
• JSONPath expressions: $.path.to.field
• JSON bodies and strings

Auto-Completion

Intelligent completions for:

• Operation IDs - After typing call ^, shows all operations from your OpenAPI spec
• Spec names - For multi-spec projects, after call using
• Fragment names - After include
• Variables - After {{ or ${, shows extracted variables
• Keywords - Step keywords with snippets
• Assertion operators - equals, contains, notEmpty, etc.
• Parameters - Call parameters based on OpenAPI operation definition

Go to Definition (F12 / Ctrl+Click / Cmd+Click)

Navigate directly to definitions with precise positioning:

• OpenAPI operations - Click on ^operationId while holding Ctrl (or Cmd on macOS) to jump to the exact line in your OpenAPI spec where the operation is defined. The target line is revealed at the top of the editor viewport for easy context.

• Spec names - After using keyword, Ctrl+Click (Cmd+Click on macOS) on the spec name (e.g., call using petstore) to open the OpenAPI specification file at the beginning.

• Fragments - Ctrl+Click (Cmd+Click on macOS) on fragment name after include to jump to the fragment definition.

• Variables - Ctrl+Click (Cmd+Click on macOS) on {{variable}} to jump to the extract statement that defined it.

Document Links (Clickable Underlines)

Operations and fragments appear as clickable, underlined text in the editor. Simply click on them to navigate:

• Operation IDs - ^operationId appears underlined; click to jump to the OpenAPI spec
• Fragments - Fragment names after include appear underlined; click to jump to the fragment definition

Document links provide visual cues without requiring modifier keys like Ctrl/Cmd.

Find All References (Shift+F12)

Find all usages of:

• Fragments - Right-click on a fragment definition or usage to find all include statements

Document Outline

View hierarchical structure in VS Code's Outline panel (Ctrl+Shift+O / Cmd+Shift+O):

• Features - Displayed as top-level Class symbols
• Scenarios/Outlines - Shown under features as Method symbols
• Background - Constructor symbol under feature
• Fragments - Function symbols at top level
• Steps - given/when/then/and/but as Field symbols under scenarios
• Examples - Array symbol under outlines
• Parameters - Struct symbol in scenarios

The outline enables:

• Quick navigation by clicking items
• Breadcrumb navigation showing current location
• Go to Symbol (Ctrl+Shift+O / Cmd+Shift+O) with type-ahead filtering

Hover Information

Hover over elements to see:

• Operation details - Method, path, parameters, request body, responses
• Fragment preview - Steps defined in the fragment
• Custom step info - Pattern, parameters, source location
• Keyword documentation - Usage examples for keywords and operators

Custom Step Discovery

The extension automatically discovers custom steps and assertions defined in your Kotlin or Java source files.

Supported Annotations:

• @Step("pattern") - Define a custom step
• @Step(pattern = "pattern") - Java style with named parameter
• @Assertion("pattern") - Define a custom assertion

Pattern Placeholders:

• {string} - Matches a quoted string (e.g., "Fluffy")
• {int} - Matches an integer (e.g., 42)
• {word} - Matches a single word (e.g., available)
• {float} - Matches a decimal number (e.g., 19.99)
• {any} - Matches any text

Example Step Definition (Kotlin):

@Step("I have a pet named {string} with status {string}")
fun createPet(name: String, status: String) {
    // ...
}

Usage in Scenario:

scenario: Test custom step
  given I have a pet named "Fluffy" with status "available"

Features:

• Auto-completion - After typing given, when, then, etc., custom steps appear in suggestions
• Go to Definition - Ctrl+Click on a custom step to navigate to its implementation
• Hover Information - See the step pattern, parameters, and source file
• Snippet Tabstops - Completions include tabstops for placeholder values

Commands:

• BerryCrush: Refresh Custom Steps - Manually reload step definitions

Document Formatting

Format your scenario and fragment files with:

• Format Document - Shift+Alt+F (or Shift+Option+F on macOS)
• Format Selection - Select text and use Ctrl+K Ctrl+F (or Cmd+K Cmd+F)
• Format on Type - Automatically format after typing : on keywords

Formatting rules:

• Root-level keywords (feature, scenario, standalone given/when/then) - no indent
• Scenario inside feature - 2 space indent
• Background inside feature - 2 space indent
• Step keywords (given, when, then, and, but) - 2 space indent from parent
• Directives (call, assert, extract, body, include, etc.) - 2 space indent from step
• Conditional blocks (if, else if, else) - same level as directives, contents +2 indent
• Table alignment - Columns aligned with pipes, numbers right-aligned, text left-aligned
• Triple-quoted blocks - Content inside """ preserved as-is

Code Folding

Collapse and expand logical sections of your scenario files:

• Features - Fold entire feature including all scenarios and background
• Scenarios/Outlines - Fold individual test scenarios
• Fragments - Fold fragment definitions
• Background - Fold background sections
• Steps - Fold given, when, then, and, but with their contents
• Parameters/Examples - Fold parameter and examples blocks
• Conditional Blocks - Fold if/else if/else blocks individually
• Triple-quoted Bodies - Fold multi-line JSON/text bodies
• Comment Blocks - Fold consecutive comment lines

Use the fold icons in the gutter, or keyboard shortcuts:

• Fold - Ctrl+Shift+[ (Cmd+Option+[ on macOS)
• Unfold - Ctrl+Shift+] (Cmd+Option+] on macOS)
• Fold All - Ctrl+K Ctrl+0 (Cmd+K Cmd+0)
• Unfold All - Ctrl+K Ctrl+J (Cmd+K Cmd+J)

Code Snippets

Type a prefix and press Tab or select from suggestions (Ctrl+Space):

Keyboard Shortcuts

Installation

From VSIX (Local Install)

1. Build the extension:

   cd contrib/vscode/berrycrush
   npm install
   npm run compile
   npm run package
   

2. Install the generated .vsix file:

   • Open VS Code
   • Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
   • Run "Extensions: Install from VSIX..."
   • Select the .vsix file

Development

1. Open the extension folder in VS Code
2. Press F5 to launch Extension Development Host
3. Open a .scenario file to test

Running Tests

Run the test suite:

cd contrib/vscode/berrycrush
npm install
npm run test

This runs the extension tests in a headless VS Code instance using @vscode/test-electron.

Configuration

Configure the extension in VS Code settings:

{
  // Single OpenAPI spec
  "berrycrush.openapi.path": "src/main/resources/openapi.yaml",
  
  // Multiple OpenAPI specs
  "berrycrush.openapi.paths": [
    "specs/petstore.yaml",
    "specs/auth.yaml"
  ],
  
  // Path to search for fragment files
  "berrycrush.fragmentsPath": "src/test/resources",
  
  // Formatting options
  "berrycrush.formatting.indentSize": 2,      // Spaces per indent level
  "berrycrush.formatting.alignTables": true   // Align table columns
}

Auto-Discovery

If no OpenAPI paths are configured, the extension automatically searches for:

• openapi.yaml, openapi.yml, openapi.json
• swagger.yaml, swagger.yml, swagger.json
• Any openapi*.yaml or swagger*.yaml files

Commands

• BerryCrush: Refresh OpenAPI - Reload OpenAPI specifications
• BerryCrush: Refresh Fragments - Reload fragment files
• BerryCrush: Refresh Custom Steps - Reload custom step definitions from source files

Requirements

• VS Code 1.85.0 or higher

Known Issues

• Large OpenAPI specs may take a moment to parse initially
• Schema validation in completions doesn't resolve $ref references

Contributing

Contributions are welcome! Please see the main berrycrush repository for contribution guidelines.

License

Apache License 2.0