Initial commit: Requirements to Gherkin CLI Converter
This commit is contained in:
Bot
234
README.md
Normal file
234
README.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# Requirements to Gherkin CLI Converter
|
||||
|
||||
[](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
|
||||
Reference in New Issue
Block a user