gherkin-formatter 0.1.0

A command-line tool to format Gherkin .feature files.

Gherkin Formatter

A Python command-line utility to format Gherkin (.feature) files, similar to how black formats Python files. This tool helps maintain consistent styling in your BDD feature specifications.

Features

• Consistent indentation for all Gherkin keywords (Feature, Scenario, Given, When, Then, etc.).
• Alignment of keywords within step blocks (Given/When/Then).
• Flexible tag formatting (single-line or multi-line).
• Automatic formatting of Data Tables with column alignment.
• Pretty-printing for JSON content within DocStrings.
• Support for Rule, Background, Scenario Outline, and Examples.
• Preserves all data; only formatting is changed.

Installation

You can install the Gherkin Formatter using pip:

pip install gherkin-formatter

Usage

gherkin-formatter [OPTIONS] [FILES_OR_DIRECTORIES...]

Arguments:

• FILES_OR_DIRECTORIES...: One or more .feature files or directories containing .feature files to format.

Options:

• --tab-width INTEGER: Number of spaces for indentation if not using tabs (default: 2). This option replaces the old --indent flag.
• --use-tabs: Indent using tabs instead of spaces. If set, --tab-width is typically ignored by the formatter for indentation character, but may influence display width in some editors.
• -a, --alignment [left|right]: Alignment for keywords (Given, When, Then, etc.) within a block of steps.
  • left: Left-aligns keywords (default).
  • right: Right-aligns keywords based on the longest keyword in the current block.
• --multi-line-tags: Formats tags each on a new line, indented. Default is --single-line-tags where all tags for an element are on a single line.
• --dry-run: Preview changes without modifying files. The formatted output (if different) will be printed to the console.
• --check: Check if files are formatted correctly. No files are changed.
  • Exits with code 0 if all files are well-formatted.
  • Exits with code 1 if one or more files would be reformatted or had file-specific processing issues (e.g., parsing errors).
  • Exits with code 123 if an internal error occurred in the formatter.
• --version: Show the program's version number and exit.
• --help: Show this message and exit.

Examples:

1. Format a single file with 4 spaces for indentation:

   gherkin-formatter --tab-width 4 my_feature.feature
   

2. Check if files in a directory are formatted correctly:

   gherkin-formatter --check features/
   

3. Preview formatting for a file, aligning keywords to the right:

   gherkin-formatter --dry-run --alignment right my_feature.feature
   

4. Format a file using tabs for indentation and multi-line tags:

   gherkin-formatter --use-tabs --multi-line-tags my_feature.feature
   

Development

This project uses pytest for testing.

To run tests:

pytest

Contributions

Contributions are welcome! Please open an issue or submit a pull request.