Skip to content

Contributing to Gherkin PowerTools

Thank you for your interest in contributing to Gherkin PowerTools! This document explains our architecture, how to set up the project locally, and how to submit your contributions.

🏗️ Architecture Overview

The extension is written in TypeScript and uses the native VS Code Extension API. It is built with performance and maintainability in mind.

Here is a breakdown of the core modules located in the src/ directory:

  • extension.ts: The entry point. Registers all commands, providers (Formatter, Definition, Outline), and initializes the diagnostics.
  • formatter.ts: The core AST-based formatter. It handles indentation, table alignment, auto-casing, and tag wrapping based on @cucumber/gherkin parses.
  • highlighter.ts: Implements custom semantic syntax highlighting via VS Code's createTextEditorDecorationType API.
  • linter.ts: Uses the official @cucumber/gherkin AST parser to perform real-time syntax checking. Generates vscode.Diagnostic warnings to underline mistakes in the editor.
  • definition.ts: The Go-To-Definition provider. Reads .feature steps and recursively searches the steps/ folder for Python (.py) files with matching @given, @when, @then decorators.
  • outline.ts: Constructs the hierarchical tree of Feature > Rule > Scenario for the VS Code Outline panel.
  • statistics.ts: Generates the interactive HTML Webview dashboard by parsing workspace files to count BDD metrics.

🛠️ Local Setup

  1. Prerequisites: Ensure you have Node.js (v16+) and npm installed.
  2. Clone the repository: 
    git clone https://github.com/carlos-camara/vscode-gherkin-powertools.git
cd vscode-gherkin-powertools
  3. Install dependencies: 
    npm install
  4. Compile the TypeScript code: 
    npm run compile
  5. Run the Extension:
  6. Press F5 in VS Code to open a new "Extension Development Host" window.
  7. Any changes you make to the code can be tested by reloading the Development Host (Cmd + R / Ctrl + R).

🧪 Testing

We use the official @vscode/test-electron framework coupled with Mocha to run tests. Our tests are split into two categories to maximize efficiency and reliability:

Unit Tests

To run ultra-fast unit tests that validate the AST processor and algorithms: 

npm run test

To run the unit tests and generate an LCOV coverage report: 

npm run coverage

End-to-End (E2E) UI Tests

To run native UI integration tests that launch a real VS Code instance and test features like formatting, outline generation, and linting directly via the VS Code Extension APIs: 

npm run test:e2e

[!IMPORTANT] Always ensure that all tests pass before submitting a Pull Request. If you are adding a new feature, please add a corresponding test case in the test/ directory.

🤖 CI/CD Pipeline

Our CI/CD pipeline leverages reusable GitHub Actions from the qa-hub-actions repository. This ensures consistency across quality checks. Specifically, coverage reporting and other QA gates are handled externally by these actions.

📦 Packaging

To create a local .vsix file for distribution or local testing:

npx vsce package

This will generate a vscode-gherkin-powertools-x.x.x.vsix file in the root directory.

🤝 Submitting a Pull Request

[!NOTE] If you are planning a large feature or significant architectural change, please open an Issue or Discussion first to align with the project maintainers before writing code.

  1. Fork the repository.
  2. Create a new branch for your feature or bug fix: git checkout -b feature/my-new-feature
  3. Commit your changes: git commit -m 'Add some feature'
  4. Push to the branch: git push origin feature/my-new-feature
  5. Open a Pull Request against the main branch.

We look forward to reviewing your code!