cucumberautocomplete

To use this extension for Cucumber (Gherkin) support in VS Code, follow these steps:

1. Open your project in VS Code.
2. Install the cucumberautocomplete extension.
3. Create a .vscode/settings.json file in your project root (if it doesn't exist):

   mkdir .vscode && touch .vscode/settings.json

4. Add the required configuration to settings.json (see configuration records).
5. Crucial: To enable autocompletion, you must ensure that editor.quickSuggestions.strings is set to true in your VS Code settings, otherwise suggestions will not appear while typing in strings.
6. Reload the VS Code window to apply changes.

You can customize the indentation and formatting of Gherkin keywords using cucumberautocomplete.formatConfOverride.

Values can be:

• A number: The specific indentation level.
• 'relative': Uses the same indentation as the next line.
• 'relativeUp': Uses the same indentation as the previous line.

Example:

"cucumberautocomplete.formatConfOverride": {
    "And": 3,
    "But": "relative"
}

Control how strictly the extension matches your typed text against step definitions:

• cucumberautocomplete.strictGherkinCompletion: When true, a step like When(/I do something/) will not appear in suggestions if you have already typed Given I. Set this to false if your framework uses non-standard step definitions (e.g., new Step('...')).
• cucumberautocomplete.strictGherkinValidation: Controls whether the extension shows errors during validation if the Gherkin word doesn't strictly match the step body.

{
    "cucumberautocomplete.strictGherkinCompletion": true,
    "cucumberautocomplete.strictGherkinValidation": true
}

The extension supports a Page Object pattern for Gherkin files, allowing you to reference structured elements using a "PageName"."ObjectName" syntax.

Mental Model

1. Pages: Defined via the pages setting. A Page is typically a file containing multiple Page Objects.
2. Page Objects: Defined within Page files using a specific syntax (e.g., ObjectName : description or ObjectName = description).
3. Usage: In your Gherkin steps, you can use autocomplete to insert these references. The extension validates these references and provides warnings if a referenced Page or Page Object cannot be found.
4. Validation: If you write "NonExistentPage"."Object", the extension will flag this with a warning diagnostic.

When smartSnippets is enabled in your settings, the autocomplete completions for steps will be transformed into VS Code snippets.

Patterns that look like user input (e.g., [a-z], *, +, or {variable}) are converted into numbered snippet placeholders (e.g., ${1:}, ${2:}). This allows you to use the Tab key to quickly jump between parameters after inserting a step.

// Example of how a step might be transformed into a snippet:
// Original: Given I have 5 apples
// Snippet: Given I have ${1:} apples

To speed up writing Gherkin steps, you can enable several productivity features:

• cucumberautocomplete.smartSnippets: Automatically converts step parts that require user input (like regex groups (.*) or (\w+)) into snippets.
• cucumberautocomplete.stepsInvariants: If a step definition uses an 'or' regex (e.g., Given(/I use (a|b)/)), this setting shows I use a and I use b as separate, distinct suggestions.
• cucumberautocomplete.onTypeFormat: Enables formatting automatically when you press keys like space, @, or :.

{
    "cucumberautocomplete.smartSnippets": true,
    "cucumberautocomplete.stepsInvariants": true,
    "cucumberautocomplete.onTypeFormat": true
}

Use the cucumberautocomplete.steps setting to tell the extension where your Gherkin step definitions are located. This accepts a single glob-style path or an array of glob-style paths.

Best Practice: Use strict paths to improve performance and accuracy. For example, test/features/step_definitions/*.steps.js is preferred over **/*.steps.js.

The extension watches these files for changes and automatically updates the step list.

{
    "cucumberautocomplete.steps": [
        "test/features/step_definitions/*.js",
        "node_modules/qa-lib/src/step_definitions/*.js"
    ]
}

If your framework uses non-standard syntax for defining steps, use these settings:

• cucumberautocomplete.gherkinDefinitionPart: Provide the RegEx pattern that identifies the step definition name part (e.g., @(given|when|then)\( for Python-like syntax).
• cucumberautocomplete.stepRegExSymbol: Specify the character used to wrap the step RegEx (e.g., ' for When('...')).
• cucumberautocomplete.pureTextSteps: Enable this if your framework treats steps as plain text rather than RegEx. It will escape special characters and wrap the text in ^ and $ anchors automatically.

{
    "cucumberautocomplete.gherkinDefinitionPart": "(Given|When|Then)\\\(",
    "cucumberautocomplete.stepRegExSymbol": "'",
    "cucumberautocomplete.pureTextSteps": true
}

The extension parses step definitions from your codebase to provide autocomplete and validation. It identifies steps by looking for Gherkin keywords (like Given, When, Then, And, But) followed by a step pattern enclosed in delimiters such as quotes ('") or forward slashes (/).

Key behaviors:

• Multi-line support: It can handle step definitions that span two lines.
• Custom Parameters: It supports replacing custom parameters defined in your settings.
• Cucumber Expressions: It automatically converts Cucumber Expressions (e.g., {int}, {float}, {string}) into regular expressions for matching.
• Documentation: It attempts to extract documentation from JSDoc-style comments preceding the step definition.

You can modify step definitions before they are parsed by applying transformations. This is useful for handling framework-specific prefixes or syntax variations.

Each object in the array can contain:

• parameter: The string or RegEx to look for.
• value: The replacement value.
• isRegex: (Optional) Boolean indicating if parameter is a regular expression.
• flags: (Optional) RegEx flags (e.g., gi).

Example: To convert @given(u'I do something') into @given('I do something') so the extension can parse it correctly:

"cucumberautocomplete.customParameters": [
    {
        "parameter": "(u'",
        "value": "('"
    }
]

"cucumberautocomplete.customParameters": [
    {
        "parameter": "{ab}",
        "value": "(a|b)"
    },
    {
        "parameter": "\\{a.*\\}",
        "value": "a",
        "isRegex": true,
        "flags": "gi"
    }
]

The extension uses a default indentation mapping for Gherkin keywords and symbols. You can customize this behavior by providing a formatConfOverride object in your settings.

Each key in the object is a Gherkin symbol (e.g., Scenario:, Given, |), and the value is the indentation level (number of indentation units) for that symbol.

Supported special values:

• relative: Indentation is determined by the nearest next line with a numeric indentation.
• relativeUp: Indentation is determined by the nearest previous line with a numeric indentation.

Default indentation levels for common symbols:

• Feature:: 0
• Rule:, Scenario:, Example:, Background:, Scenario Outline:: 1
• Examples:, Given, When, Then, And, But, *: 2
• |, """: 3

{
  "cucumberautocomplete.formatConfOverride": {
    "Scenario:": 2,
    "Given": 3,
    "|": 4
  }
}

You can control how the extension interacts with your Gherkin files using the following settings:

• pages: A mapping of page names to their respective identifiers ({[page: string]: string}).
• formatConfOverride: An object used to override formatting configurations. Values can be a number, 'relative', or 'relativeUp'.
• onTypeFormat: A boolean that determines if formatting should occur while typing.
• skipDocStringsFormat: A boolean to skip formatting for DocStrings.
• pureTextSteps: A boolean to treat steps as pure text.
• gherkinDefinitionPart: An optional string to specify the part of the Gherkin definition to use.