Orchestrata Ultimate › Plans › bdd_cucumber_gherkin_setup

Plan: Install and Configure Cucumber and Gherkin for BDD Testing

Source: plans/bdd_cucumber_gherkin_setup.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-04-11 · 158 lines.

Prose pending.

Plan text

Plan: Install and Configure Cucumber and Gherkin for BDD Testing

Overview

Add Behavior-Driven Development (BDD) testing support to orchestrata-ultimate using Cucumber/Gherkin syntax. This will enable writing tests in natural language that can be understood by both technical and non-technical stakeholders.

Options for Python BDD Testing

1. behave (Traditional Cucumber-style)

• Pure Cucumber implementation for Python
• Uses .feature files with Gherkin syntax
• Step definitions in Python
• Standalone runner

2. pytest-bdd (Pytest Integration)

• Integrates with existing pytest infrastructure
• Uses .feature files with Gherkin syntax
• Leverages pytest fixtures and plugins
• Better integration with existing test suite

Recommendation: pytest-bdd

Given that orchestrata-ultimate already uses pytest extensively, pytest-bdd is recommended for better integration.

Implementation Steps

1. Install Dependencies

cd /home/mohamed/workspace/orchestrata-ultimate
uv add pytest-bdd

Add to pyproject.toml dev dependencies:

[project.optional-dependencies]
dev = [
    # ... existing dependencies
    "pytest-bdd>=6.0.0",
]

2. Create Directory Structure

tests/features/
├── steps/           # Step definitions
├── features/        # .feature files
└── conftest.py      # Shared fixtures

3. Create Example Feature File

tests/features/features/example.feature:

Feature: Orchestrata Ultimate API
  As a developer
  I want to verify API endpoints
  So that I can ensure system reliability

  Scenario: Health check endpoint
    Given the orchestrata API is running
    When I request GET /health
    Then the response status should be 200
    And the response should contain "status": "healthy"

4. Create Step Definitions

tests/features/steps/api_steps.py:

import pytest
from pytest_bdd import given, when, then, parsers
import httpx

@given("the orchestrata API is running", target_fixture="client")
def api_client():
    """Create API client fixture."""
    return httpx.AsyncClient(base_url="http://localhost:8000")

@when("I request GET /health")
async def request_health_check(client):
    """Make health check request."""
    response = await client.get("/health")
    return response

@then("the response status should be 200")
def check_response_status(request_health_check):
    """Verify response status."""
    assert request_health_check.status_code == 200

@then(parsers.parse('the response should contain "{expected_text}"'))
def check_response_content(request_health_check, expected_text):
    """Verify response content."""
    assert expected_text in request_health_check.text

5. Configure Pytest for BDD

tests/features/conftest.py:

import pytest
from pytest_bdd import scenarios

# Auto-discover feature files
scenarios("features/")

6. Update Pytest Configuration

Add to pyproject.toml:

[tool.pytest.ini_options]
testpaths = ["tests", "tests/features"]
asyncio_mode = "auto"
addopts = [
    "--strict-markers",
    "--strict-config",
    "--tb=short",
    "-v",
]

7. Create BDD Test Generator

Extend existing generate_pytest.py to also generate BDD feature files from method documentation or specifications.

8. Integration with Existing Tests

• Keep existing unit tests for low-level functionality
• Use BDD for integration and acceptance tests
• Generate BDD scenarios from API specifications

Example: Generating BDD Tests from AST

Extend generate_pytest.py to create BDD feature files for public APIs:

class BDDGenerator:
    """Generate BDD feature files from method information."""
    
    def generate_bdd_tests(self, methods: List[MethodInfo], output_dir: Path):
        """Generate BDD feature files."""
        for method in methods:
            if self._should_generate_bdd(method):
                self._create_feature_file(method, output_dir)
                self._create_step_definitions(method, output_dir)

Benefits

1. Business Readable Tests: Non-technical stakeholders can understand test scenarios
2. Living Documentation: Feature files serve as up-to-date documentation
3. Collaboration: Bridges gap between business and development teams
4. Test Generation: Can auto-generate BDD tests from API specs or method docs

Success Criteria

• [ ] pytest-bdd installed and working
• [ ] Example feature file created and passing
• [ ] Directory structure for BDD tests established
• [ ] Integration with existing pytest setup
• [ ] At least 3 BDD scenarios for core functionality

Timeline

• Immediate: Install dependencies and create example (1 hour)
• Short-term: Create BDD tests for key API endpoints (2-3 hours)
• Long-term: Integrate BDD test generation into existing test generator

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks