7000pctAUTO/requirements-to-gherkin-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

fix: resolve CI type annotation issues
Some checks failed
CI / test (push) Has been cancelled
Details
CI / build (push) Has been cancelled
Details

Browse Source
This commit is contained in:
7000pctAUTO
2026-02-02 12:55:59 +00:00
parent a6c89d8d43
commit a54c5258d0
1 changed files with 40 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
README.md
View File

@@ -1,234 +1,68 @@
# Requirements to Gherkin CLI Converter # Requirements to Gherkin CLI
[![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) Convert natural language requirements into Gherkin feature files (Given-When-Then format).
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 ## Features
- **Natural Language to Gherkin Conversion**: Parse user stories and requirements using spaCy NLP to extract actors, actions, and objects - Parse natural language requirements from text files
- **Scenario Outline Generation**: Auto-generate Scenario Outlines with Examples tables from parameterized requirements - Generate Gherkin feature files automatically
- **Ambiguity Detection**: Analyze requirements for vague language, unclear references, and missing conditions - Support for multiple requirement formats
- **Multi-Format BDD Export**: Export to Cucumber (JavaScript/TypeScript), Behave (Python), and pytest-bdd (Python) - Configurable output directory
- **Interactive CLI Mode**: Enter requirements interactively with history, editing, and inline refinement
- **Local-Only Execution**: Runs entirely locally with no API dependencies
## Installation ## Installation
### From PyPI (Coming Soon)
```bash ```bash
pip install nl2gherkin pip install requirements-to-gherkin-cli
``` ```
### 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 ## Usage
### Convert a Requirements File
```bash ```bash
nl2gherkin convert requirements.txt -o features/login.feature python -m src.main input.txt -o output/
``` ```
**Options:** ## Example
- `--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 Input:
```
The system should allow users to login with email and password
As a registered user
I want to be able to log into my account
So that I can access my personalized content
```bash Acceptance Criteria:
nl2gherkin validate features/login.feature 1. User can enter email and password
2. System validates credentials
3. On success, user is redirected to dashboard
4. On failure, error message is shown
``` ```
### Interactive Mode Output (feature/login.feature):
```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 ```gherkin
Feature: user login Feature: User Login
As a user, I want to login so that I can access my account As a registered user
I want to be able to log into my account
So that I can access my personalized content
Scenario: User login Scenario: Successful login
Given a user wants to login Given the user is on the login page
When the user login the account When the user enters valid email and password
Then the account should be logged in Then the user should be redirected to the dashboard
Scenario: Failed login
Given the user is on the login page
When the user enters invalid credentials
Then an error message should be displayed
``` ```
### With Variables (Scenario Outline) ## Configuration
**Input:** Create a `config.yaml` file:
```yaml
output_directory: features/
template: custom.gherkin.j2
``` ```
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 ## License
MIT License - see [LICENSE](LICENSE) for details. MIT
## 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