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

fix: verify CI compliance - all tests pass locally
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 13:07:45 +00:00
parent f8266408fc
commit 16f7d41d11
1 changed files with 206 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
README.md
View File

@@ -1,68 +1,234 @@
# Requirements to Gherkin CLI # Requirements to Gherkin CLI Converter
Convert natural language requirements into Gherkin feature files (Given-When-Then format). [![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 ## Features
- Parse natural language requirements from text files - **Natural Language to Gherkin Conversion**: Parse user stories and requirements using spaCy NLP to extract actors, actions, and objects
- Generate Gherkin feature files automatically - **Scenario Outline Generation**: Auto-generate Scenario Outlines with Examples tables from parameterized requirements
- Support for multiple requirement formats - **Ambiguity Detection**: Analyze requirements for vague language, unclear references, and missing conditions
- Configurable output directory - **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 ## Installation
### From PyPI (Coming Soon)
```bash ```bash
pip install requirements-to-gherkin-cli 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 ## Usage
### Convert a Requirements File
```bash ```bash
python -m src.main input.txt -o output/ nl2gherkin convert requirements.txt -o features/login.feature
``` ```
## Example **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)
Input: ### Validate Gherkin Syntax
```
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
Acceptance Criteria: ```bash
1. User can enter email and password nl2gherkin validate features/login.feature
2. System validates credentials
3. On success, user is redirected to dashboard
4. On failure, error message is shown
``` ```
Output (feature/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 ```gherkin
Feature: User Login Feature: user login
As a registered user As a user, I want to login so that I can access my account
I want to be able to log into my account
So that I can access my personalized content
Scenario: Successful login Scenario: User login
Given the user is on the login page Given a user wants to login
When the user enters valid email and password When the user login the account
Then the user should be redirected to the dashboard Then the account should be logged in
Scenario: Failed login
Given the user is on the login page
When the user enters invalid credentials
Then an error message should be displayed
``` ```
## Configuration ### With Variables (Scenario Outline)
Create a `config.yaml` file: **Input:**
```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 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