refactor: update BDD testing documentation and enhance async step implementations

- Clarified the usage of the Behave BDD framework, specifying version 1.3.3.
- Added details on the directory structure for BDD tests, including new files for global setup and shared utilities.
- Updated async step implementations to use `await` instead of `asyncio.run()`, ensuring proper async handling.
- Removed deprecated utility functions from `test_helpers.py` to streamline the codebase.
- Adjusted linting exclusions and documentation for better clarity and organization.

Author: HosseinNejatiJavaremi

.cursor/rules/testing-bdd.mdc

@@ -6,37 +6,32 @@ alwaysApply: false
 
 # Testing with BDD (Behave)
 
-ArchiPy uses the **Behave** BDD framework. Tests are written as Gherkin scenarios.
+ArchiPy uses the **Behave** BDD framework (v1.3.3). Tests are written as Gherkin scenarios.
 
 ## Directory Structure
 
 ```
 features/
-├── *.feature          # Gherkin scenario files
+├── *.feature                    # Gherkin scenario files
+├── environment.py               # Global setup/teardown hooks
+├── scenario_context.py          # Per-scenario state container
+├── test_helpers.py              # Shared async/sync utilities
 └── steps/
-    └── *.py           # Step implementations (Given/When/Then)
+    └── *.py                     # Step implementations (Given/When/Then)
 ```
 
 ## Running Tests
 
 ```bash
-# All tests
 make behave
-# or:
-uv run --extra behave behave
-
-# Single feature file
 uv run --extra behave behave features/file_name.feature
-
-# Specific scenario (by line number)
 uv run --extra behave behave features/file_name.feature:42
 ```
 
 ## Writing Feature Files
 
 - Keep `.feature` files **declarative** — describe behavior, not implementation.
 - Use `@tags` to categorize scenarios for selective runs.
-- Avoid logic in `.feature` files; all logic belongs in `features/steps/`.
 
 ```gherkin
 # ✅ GOOD
@@ -52,29 +47,32 @@ Feature: Cache adapter
 
 - Step functions are exempt from: `ANN001`, `ANN201`, `ARG001`, `PLR0913`, `F811`.
 - Step redefinition (`F811`) is allowed — Behave reuses steps across features.
-- Use `context` to share state between steps within a scenario.
-
-```python
-# ✅ GOOD
-from behave import given, then, when
+- Use `get_current_scenario_context(context)` to share state between steps.
 
-@given("a running Redis instance")
-def step_redis_running(context):
-    context.redis = FakeRedisAdapter()
+## Async Steps
 
-@when('I store "{value}" under key "{key}"')
-def step_store_value(context, value, key):
-    context.redis.set(key, value)
+Behave 1.3.3 supports `async def` step functions **natively** — no `asyncio.run()` or `@async_run_until_complete` wrapper needed. Always declare async steps with `async def` and use `await` directly.
 
-@then('I can retrieve "{value}" from key "{key}"')
-def step_retrieve_value(context, value, key):
-    assert context.redis.get(key) == value
+```python
+# ❌ BAD — never use asyncio.run() inside a step
+@when("something async happens")
+def step_impl(context):
+    result = asyncio.run(some_async_call())
+
+# ✅ GOOD — declare the step as async def and await directly
+@when("something async happens")
+async def step_impl(context):
+    result = await some_async_call()
 ```
 
+Sync operations work fine inside `async def` steps, so steps with mixed sync/async branches (e.g. if/elif over frameworks) should be converted to `async def` entirely.
+
+The only place `asyncio.run()` is acceptable is in **non-step** callbacks (e.g. `scenario_context.py` cleanup methods) that may be called from outside an event loop.
+
 ## Parallel Execution
 
-Behave is configured to run with **8 parallel workers** (multiprocessing). Ensure steps do not share mutable global state across scenarios.
+Behave is configured to run with **8 parallel workers** (multiprocessing). Steps must not share mutable global state across scenarios.
 
 ## Linting Exclusions
 
-`features/` and `scripts/` directories are excluded from Ruff linting (`exclude` in `pyproject.toml`). Do not add type annotations to step functions.
+`features/` and `scripts/` are excluded from Ruff linting. Do not add type annotations to step functions.

archipy/configs/config_template.py

@@ -49,7 +49,7 @@ class ElasticsearchConfig(BaseModel):
     RETRY_ON_TIMEOUT: bool = Field(default=True, description="Retry on connection timeouts")
     RETRY_ON_STATUS: tuple[int, ...] = Field(default=(429, 502, 503, 504), description="HTTP status codes to retry on")
     IGNORE_STATUS: tuple[int, ...] = Field(default=(), description="HTTP status codes to ignore as errors")
-    SNIFF_ON_START: bool = Field(default=True, description="Sniff nodes on client instantiation")
+    SNIFF_ON_START: bool = Field(default=False, description="Sniff nodes on client instantiation")
     SNIFF_BEFORE_REQUESTS: bool = Field(default=False, description="Sniff nodes before requests")
     SNIFF_ON_NODE_FAILURE: bool = Field(default=True, description="Sniff nodes on node failure")
     MIN_DELAY_BETWEEN_SNIFFING: float = Field(

features/steps/atomic_transaction_steps.py

@@ -4,7 +4,6 @@
 atomic transaction scenarios.
 """
 
-import asyncio
 import logging
 import os
 import tempfile
@@ -141,7 +140,7 @@ def _get_adapter_classes(db_type: str):
 
 
 @given("the application database is initialized for {db_type}")
-def step_given_database_initialized(context, db_type: str):
+async def step_given_database_initialized(context, db_type: str):
     """Initialize the database for testing with the specified database type.
 
     Args:
@@ -189,7 +188,7 @@ def step_given_database_initialized(context, db_type: str):
 
                 # Create schema with async adapter
                 logger.info("Creating database schema with async PostgreSQL adapter")
-                asyncio.run(async_schema_setup(async_adapter))
+                await async_schema_setup(async_adapter)
 
                 logger.info("Async PostgreSQL adapter and schema setup completed")
             except Exception as e:
@@ -251,7 +250,7 @@ def step_given_database_initialized(context, db_type: str):
 
                 # Create schema with async adapter
                 logger.info("Creating database schema with async SQLite adapter")
-                asyncio.run(async_schema_setup(async_adapter))
+                await async_schema_setup(async_adapter)
 
                 logger.info("Async SQLite adapter and schema setup completed")
             except Exception as e:

features/steps/error_utils_steps.py

@@ -1,4 +1,3 @@
-import asyncio
 from http import HTTPStatus
 from unittest.mock import patch
 
@@ -78,7 +77,7 @@ def step_given_fastapi_error(context, error_type):
 
 
 @when("an async FastAPI error is handled")
-def step_when_fastapi_error_is_handled(context):
+async def step_when_fastapi_error_is_handled(context):
     scenario_context = get_current_scenario_context(context)
     fastapi_error = scenario_context.get("fastapi_error")
 
@@ -90,7 +89,7 @@ async def handle_error():
             status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
             content={"detail": "Error occurred"},
         )
-        http_status = asyncio.run(handle_error()).status_code
+        http_status = (await handle_error()).status_code
         scenario_context.store("http_status", http_status)
 
 

features/steps/grpc_error_handling_steps.py

@@ -1,7 +1,5 @@
 """Step definitions for gRPC error handling tests."""
 
-import asyncio
-
 from behave import given, then, when
 
 from archipy.models.errors import (
@@ -116,7 +114,7 @@ def step_when_sync_grpc_raises_error(context, error_type: str):
 
 
 @when('an async gRPC method raises "{error_type}" error')
-def step_when_async_grpc_raises_error(context, error_type: str):
+async def step_when_async_grpc_raises_error(context, error_type: str):
     """Test an async gRPC method that raises a specific error using real gRPC calls."""
     scenario_context = get_current_scenario_context(context)
 
@@ -149,7 +147,7 @@ async def make_call():
 
         return grpc_error
 
-    grpc_error = asyncio.run(make_call())
+    grpc_error = await make_call()
 
     scenario_context.store("grpc_error", error_instance)
     scenario_context.store("grpc_rpc_error", grpc_error)
@@ -195,7 +193,7 @@ def step_when_sync_grpc_invalid_request(context):
 
 
 @when("an async gRPC method receives invalid request")
-def step_when_async_grpc_invalid_request(context):
+async def step_when_async_grpc_invalid_request(context):
     """Test an async gRPC method that receives invalid request using real gRPC calls."""
     scenario_context = get_current_scenario_context(context)
 
@@ -220,7 +218,7 @@ async def make_call():
 
         return grpc_error
 
-    grpc_error = asyncio.run(make_call())
+    grpc_error = await make_call()
 
     # The interceptor converts ValidationError to InvalidArgumentError
     from archipy.models.errors import InvalidArgumentError
@@ -277,7 +275,7 @@ def step_when_sync_grpc_unexpected_error(context):
 
 
 @when("an async gRPC method raises an unexpected exception")
-def step_when_async_grpc_unexpected_error(context):
+async def step_when_async_grpc_unexpected_error(context):
     """Test an async gRPC method that raises an unexpected exception using real gRPC calls."""
     scenario_context = get_current_scenario_context(context)
 
@@ -303,7 +301,7 @@ async def make_call():
 
         return grpc_error
 
-    grpc_error = asyncio.run(make_call())
+    grpc_error = await make_call()
 
     # The interceptor converts unexpected errors to InternalError
     from archipy.models.errors import InternalError
@@ -521,7 +519,7 @@ def step_when_sync_grpc_raises_validation_error_with_lang(context, error_type: s
 
 
 @when('an async gRPC method raises "{error_type}" validation error with value "{invalid_value}" in language "{lang}"')
-def step_when_async_grpc_raises_validation_error_with_lang(context, error_type: str, invalid_value: str, lang: str):
+async def step_when_async_grpc_raises_validation_error_with_lang(context, error_type: str, invalid_value: str, lang: str):
     """Test an async gRPC method that raises a validation error with a specific value and language."""
     scenario_context = get_current_scenario_context(context)
 
@@ -564,7 +562,7 @@ async def make_call():
 
         return grpc_error
 
-    grpc_error = asyncio.run(make_call())
+    grpc_error = await make_call()
 
     scenario_context.store("grpc_error", error_instance)
     scenario_context.store("grpc_rpc_error", grpc_error)

features/steps/metric_interceptor_steps.py

@@ -167,7 +167,7 @@ def step_when_metric_interceptor_setup(context, framework):
 
 
 @when("a {framework} request is made")
-def step_when_request_made(context, framework):
+async def step_when_request_made(context, framework):
     scenario_context = get_current_scenario_context(context)
 
     if framework == "FastAPI":
@@ -226,8 +226,6 @@ def mock_method(request, context):
         scenario_context.store("final_active_requests", final_active)
 
     elif framework == "AsyncgRPC":
-        import asyncio
-
         interceptors = scenario_context.get("interceptors")
 
         if not interceptors or not isinstance(interceptors[0], AsyncGrpcServerMetricInterceptor):
@@ -255,7 +253,7 @@ async def mock_method(request, context):
         )
 
         # Run the async interceptor
-        result = asyncio.run(interceptor.intercept(mock_method, {}, mock_context, method_name_model))
+        result = await interceptor.intercept(mock_method, {}, mock_context, method_name_model)
         scenario_context.store("result", result)
 
         final_metrics = _get_metric_samples("grpc_async_response_time_seconds")

features/test_helpers.py

@@ -1,8 +1,4 @@
-"""This module provides utilities to help with async testing in behave.
-
-It focuses on solving the problem of SQLAlchemy async scoped sessions
-using current_task() for scoping, which can cause issues in behave tests.
-"""
+"""Shared utilities for Behave BDD step implementations."""
 
 from archipy.models.entities import BaseEntity
 
@@ -58,74 +54,6 @@ def get_async_adapter(context):
     return async_adapter
 
 
-def safe_has_attr(obj, attr):
-    """A truly safe way to check if an attribute exists on an object.
-
-    This uses the __dict__ directly rather than hasattr() which can
-    trigger __getattr__ and raise exceptions.
-
-    Args:
-        obj: The object to check
-        attr: The attribute name to check for
-
-    Returns:
-        bool: True if the attribute exists, False otherwise
-    """
-    # For Context objects in behave, check the dictionary directly
-    if hasattr(obj, "__dict__"):
-        return attr in obj.__dict__
-
-    # Fallback to normal hasattr for other objects
-    try:
-        return hasattr(obj, attr)
-    except:
-        return False
-
-
-def safe_get_attr(obj, attr, default=None):
-    """A truly safe way to get an attribute from an object.
-
-    This uses the __dict__ directly rather than getattr() which can
-    trigger __getattr__ and raise exceptions.
-
-    Args:
-        obj: The object to get the attribute from
-        attr: The attribute name to get
-        default: The default value to return if the attribute doesn't exist
-
-    Returns:
-        The attribute value, or the default if it doesn't exist
-    """
-    # For Context objects in behave, check the dictionary directly
-    if hasattr(obj, "__dict__"):
-        return obj.__dict__.get(attr, default)
-
-    # Fallback to normal getattr for other objects
-    try:
-        return getattr(obj, attr, default)
-    except:
-        return default
-
-
-def safe_set_attr(obj, attr, value):
-    """A truly safe way to set an attribute on an object.
-
-    This uses the __dict__ directly rather than setattr() which can
-    trigger __getattr__ and raise exceptions.
-
-    Args:
-        obj: The object to set the attribute on
-        attr: The attribute name to set
-        value: The value to set
-    """
-    # For Context objects in behave, set the dictionary directly
-    if hasattr(obj, "__dict__"):
-        obj.__dict__[attr] = value
-    else:
-        # Fallback to normal setattr for other objects
-        setattr(obj, attr, value)
-
-
 async def async_schema_setup(async_adapter):
     """Set up database schema for async adapter."""
     # Use AsyncEngine.begin() for proper transaction handling