requirements-to-gherkin-cli/README.md

# Requirements to Gherkin CLI Converter

[![CI/CD](https://7000pct.gitea.bloupla.net/7000pctAUTO/requirements-to-gherkin-cli/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/requirements-to-gherkin-cli/actions)

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)

```bash
pip install nl2gherkin
```

### From Source

```bash
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

```bash
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

```bash
nl2gherkin validate features/login.feature
```

### Interactive Mode

```bash
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)

```gherkin
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:**
```gherkin
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)

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

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

### Behave (Python)

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

Generates Python step definitions for Behave with environment configuration.

### pytest-bdd (Python)

```bash
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

```bash
# 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:

```bash
# 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](LICENSE) for details.

## Acknowledgments

- [spaCy](https://spacy.io/) for natural language processing
- [Gherkin Official](https://github.com/cucumber/gherkin) for Gherkin parsing
- [Click](https://click.palletsprojects.com/) for CLI functionality