Requirements to Gherkin CLI Converter

A powerful CLI tool that converts natural language project requirements into structured acceptance criteria in Gherkin format (Given-When-Then). Perfect for developers, QA engineers, and product managers who practice Behavior-Driven Development (BDD).

Features

• Natural Language to Gherkin Conversion: Parse user stories and requirements using spaCy NLP to extract actors, actions, and objects
• Scenario Outline Generation: Auto-generate Scenario Outlines with Examples tables from parameterized requirements
• Ambiguity Detection: Analyze requirements for vague language, unclear references, and missing conditions
• Multi-Format BDD Export: Export to Cucumber (JavaScript/TypeScript), Behave (Python), and pytest-bdd (Python)
• Interactive CLI Mode: Enter requirements interactively with history, editing, and inline refinement
• Local-Only Execution: Runs entirely locally with no API dependencies

Installation

From PyPI (Coming Soon)

pip install nl2gherkin

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/requirements-to-gherkin-cli.git
cd requirements-to-gherkin-cli
pip install -e .

Dependencies

The tool requires:

• Python 3.9+
• spaCy with en_core_web_sm model (downloaded automatically)
• Gherkin parser

Usage

Convert a Requirements File

nl2gherkin convert requirements.txt -o features/login.feature

Options:

• --framework, -f: BDD framework (cucumber, behave, pytest-bdd)
• --output, -o: Output file path
• --validate/--no-validate: Validate Gherkin syntax (default: True)
• --ambiguity-check/--no-ambiguity-check: Check for ambiguous language (default: True)

Validate Gherkin Syntax

nl2gherkin validate features/login.feature

Interactive Mode

nl2gherkin interactive --framework behave

Enter requirements interactively, edit generated scenarios, and export when ready.

Examples

Input (requirements.txt)

As a user, I want to login so that I can access my account
As an admin, I want to manage users so that I can control access

Output (login.feature)

Feature: user login
  As a user, I want to login so that I can access my account

  Scenario: User login
    Given a user wants to login
    When the user login the account
    Then the account should be logged in

With Variables (Scenario Outline)

Input:

As a user, I want to search for <product> so that I can find it

Output:

Feature: user search
  As a user, I want to search for <product> so that I can find it

  Scenario Outline: User search product
    Given a user wants to search
    When the user search the product
    Then the product should be displayed

    Examples:
      | product |
      | value   |

Framework Export

Cucumber (JavaScript/TypeScript)

nl2gherkin convert requirements.txt --framework cucumber -o features/

Generates step definition templates for Cucumber.js with configuration files.

Behave (Python)

nl2gherkin convert requirements.txt --framework behave -o features/

Generates Python step definitions for Behave with environment configuration.

pytest-bdd (Python)

nl2gherkin convert requirements.txt --framework pytest-bdd -o features/

Generates pytest fixture-based step definitions with conftest.py.

Ambiguity Detection

The tool detects ambiguous language in requirements:

Type	Example	Suggestion
Pronouns	"When it is clicked"	Replace with specific noun
Vague quantifiers	"Some users"	Specify exact number
Temporal terms	"Complete soon"	Specify exact deadline
Missing conditions	"User must login"	Add "when" condition
Passive voice	"Was created by"	Use active voice

Example warning:

[WARNING] Vague quantifier 'some' lacks precision
  Suggestion: Specify an exact number or range for 'some'

Development

Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Download spaCy model
python -m spacy download en_core_web_sm

# Run tests
pytest tests/ -v

# Run linting
black src/ tests/
mypy src/

Project Structure

requirements-to-gherkin-cli/
├── src/nl2gherkin/
│   ├── cli/           # Command-line interface
│   │   ├── commands.py
│   │   └── interactive.py
│   ├── nlp/           # Natural language processing
│   │   ├── analyzer.py
│   │   ├── ambiguity.py
│   │   └── patterns.py
│   ├── gherkin/       # Gherkin generation
│   │   ├── generator.py
│   │   ├── parser.py
│   │   └── templates.py
│   └── exporters/     # BDD framework exporters
│       ├── base.py
│       ├── cucumber.py
│       ├── behave.py
│       └── pytest_bdd.py
├── tests/             # Unit tests
├── pyproject.toml
└── README.md

Testing

The project includes comprehensive tests:

# Run all tests with coverage
pytest tests/ -v --cov=src/nl2gherkin --cov-report=term-missing

# Run specific test file
pytest tests/test_analyzer.py -v

# Run with detailed output
pytest tests/ -vv

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• spaCy for natural language processing
• Gherkin Official for Gherkin parsing
• Click for CLI functionality