Address Copilot comments (1)

Signed-off-by: Sergio Herrera <627709+seherv@users.noreply.github.com>

Author: seherv

AGENTS.md

@@ -65,10 +65,8 @@ Each extension is a **separate PyPI package** with its own `setup.cfg`, `setup.p
 
 The `examples/` directory contains user-facing example applications. These are validated by two test suites:
 
-- **`tests/examples/`** — Output-based tests that run examples via `dapr run` and check stdout for expected strings. Uses a `DaprRunner` helper to manage process lifecycle.
-- **`tests/integration/`** — Programmatic SDK tests that call `DaprClient` methods directly and assert on return values, gRPC status codes, and SDK types. More reliable than output-based tests since they don't depend on print statement formatting.
-
-**See `examples/AGENTS.md`** for the full guide on example structure and how to add new examples.
+- **`tests/examples/`** — Output-based tests that run examples via `dapr run` and check stdout for expected strings. Uses a `DaprRunner` helper to manage process lifecycle. See `examples/AGENTS.md`.
+- **`tests/integration/`** — Programmatic SDK tests that call `DaprClient` methods directly and assert on return values, gRPC status codes, and SDK types. More reliable than output-based tests since they don't depend on print statement formatting. See `tests/integration/AGENTS.md`.
 
 Quick reference:
 ```bash

examples/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — Dapr Python SDK Examples
 
-The `examples/` directory serves as both **user-facing documentation** and the project's **integration test suite**. Each example is a self-contained application validated by pytest-based tests in `tests/examples/`.
+The `examples/` directory serves as the **user-facing documentation**. Each example is a self-contained application validated by pytest-based tests in `tests/examples/`.
 
 ## How validation works
 

examples/conversation/real_llm_providers_example.py

@@ -1237,7 +1237,7 @@ def main():
 
         print(f'\n{"=" * 60}')
         print('🎉 All Alpha2 tests completed!')
-        print('✅ Real LLM provider examples with Alpha2 API is working correctly')
+        print('✅ Real LLM provider integration with Alpha2 API is working correctly')
         print('🔧 Features demonstrated:')
         print('   • Alpha2 conversation API with sophisticated message types')
         print('   • Automatic parameter conversion (raw Python values)')

tests/clients/test_conversation_helpers.py

@@ -1511,7 +1511,7 @@ def google_function(data: str):
 
 
 class TestIntegrationScenarios(unittest.TestCase):
-    """Test real-world examples scenarios."""
+    """Test real-world integration scenarios."""
 
     def test_restaurant_finder_scenario(self):
         """Test the restaurant finder example from the documentation."""

tests/integration/AGENTS.md

@@ -0,0 +1,94 @@
+# AGENTS.md — Programmatic Integration Tests
+
+This directory contains **programmatic SDK tests** that call `DaprClient` methods directly and assert on return values, gRPC status codes, and SDK types. Unlike the output-based tests in `tests/examples/` (which run example scripts and check stdout), these tests don't depend on print statement formatting.
+
+## How it works
+
+1. `DaprTestEnvironment` (defined in `conftest.py`) manages Dapr sidecar processes
+2. `start_sidecar()` launches `dapr run` with explicit ports, waits for the health check, and returns a connected `DaprClient`
+3. Tests call SDK methods on that client and assert on the response objects
+4. Sidecar stdout is written to temp files (not pipes) to avoid buffer deadlocks
+5. Cleanup terminates sidecars, closes clients, and removes log files
+
+Run locally (requires a running Dapr runtime via `dapr init`):
+
+```bash
+# All integration tests
+tox -e integration
+
+# Single test file
+tox -e integration -- test_state_store.py
+
+# Single test
+tox -e integration -- test_state_store.py -k test_save_and_get
+```
+
+## Directory structure
+
+```
+tests/integration/
+├── conftest.py              # DaprTestEnvironment + fixtures (dapr_env, apps_dir, components_dir)
+├── test_*.py                # Test files (one per building block)
+├── apps/                    # Helper apps started alongside sidecars
+│   ├── invoke_receiver.py   # gRPC method handler for invoke tests
+│   └── pubsub_subscriber.py # Subscriber that persists messages to state store
+├── components/              # Dapr component YAMLs loaded by all sidecars
+│   ├── statestore.yaml      # state.redis
+│   ├── pubsub.yaml          # pubsub.redis
+│   ├── lockstore.yaml       # lock.redis
+│   ├── configurationstore.yaml # configuration.redis
+│   └── localsecretstore.yaml   # secretstores.local.file
+└── secrets.json             # Secrets file for localsecretstore component
+```
+
+## Fixtures
+
+All fixtures are **module-scoped** — one sidecar per test file.
+
+| Fixture | Type | Description |
+|---------|------|-------------|
+| `dapr_env` | `DaprTestEnvironment` | Manages sidecar lifecycle; call `start_sidecar()` to get a client |
+| `apps_dir` | `Path` | Path to `tests/integration/apps/` |
+| `components_dir` | `Path` | Path to `tests/integration/components/` |
+
+Each test file defines its own module-scoped `client` fixture that calls `dapr_env.start_sidecar(...)`.
+
+## Building blocks covered
+
+| Test file | Building block | SDK methods tested |
+|-----------|---------------|-------------------|
+| `test_state_store.py` | State management | `save_state`, `get_state`, `save_bulk_state`, `get_bulk_state`, `execute_state_transaction`, `delete_state` |
+| `test_invoke.py` | Service invocation | `invoke_method` |
+| `test_pubsub.py` | Pub/sub | `publish_event`, `get_state` (to verify delivery) |
+| `test_secret_store.py` | Secrets | `get_secret`, `get_bulk_secret` |
+| `test_metadata.py` | Metadata | `get_metadata`, `set_metadata` |
+| `test_distributed_lock.py` | Distributed lock | `try_lock`, `unlock`, context manager |
+| `test_configuration.py` | Configuration | `get_configuration`, `subscribe_configuration`, `unsubscribe_configuration` |
+
+## Port allocation
+
+All sidecars default to gRPC port 50001 and HTTP port 3500. Since fixtures are module-scoped and tests run sequentially, only one sidecar is active at a time. If parallel execution is needed in the future, sidecars will need dynamic port allocation.
+
+## Helper apps
+
+Some building blocks (invoke, pubsub) require an app process running alongside the sidecar:
+
+- **`invoke_receiver.py`** — A `dapr.ext.grpc.App` that handles `my-method` and returns `INVOKE_RECEIVED`.
+- **`pubsub_subscriber.py`** — Subscribes to `TOPIC_A` and persists received messages to the state store. This lets tests verify message delivery by reading state rather than parsing stdout.
+
+## Adding a new test
+
+1. Create `test_<building_block>.py`
+2. Add a module-scoped `client` fixture that calls `dapr_env.start_sidecar(app_id='test-<name>')`
+3. If the building block needs a new Dapr component, add a YAML to `components/`
+4. If the building block needs a running app, add it to `apps/` and pass `app_cmd` / `app_port` to `start_sidecar()`
+5. Use unique keys/resource IDs per test to avoid interference (the sidecar is shared within a module)
+6. Assert on SDK return types and gRPC status codes, not on string output
+
+## Gotchas
+
+- **Requires `dapr init`** — the tests assume a local Dapr runtime with Redis (`dapr_redis` container on `localhost:6379`), which `dapr init` sets up automatically.
+- **Configuration tests seed Redis directly** via `docker exec dapr_redis redis-cli`.
+- **Lock and configuration APIs are alpha** and emit `UserWarning` on every call. Tests suppress these with `pytestmark = pytest.mark.filterwarnings('ignore::UserWarning')`.
+- **`localsecretstore.yaml` uses a relative path** (`secrets.json`) resolved against `cwd=INTEGRATION_DIR`.
+- **Dapr may normalize response fields** — e.g., `content_type` may lose charset parameters when proxied through gRPC. Assert on the media type prefix, not the full string.

tests/integration/conftest.py

@@ -8,6 +8,7 @@
 import pytest
 
 from dapr.clients import DaprClient
+from dapr.conf import settings
 
 INTEGRATION_DIR = Path(__file__).resolve().parent
 COMPONENTS_DIR = INTEGRATION_DIR / 'components'
@@ -42,9 +43,8 @@ def start_sidecar(
 
         Args:
             app_id: Dapr application ID.
-            grpc_port: Sidecar gRPC port (must match DAPR_GRPC_PORT setting).
-            http_port: Sidecar HTTP port (must match DAPR_HTTP_PORT setting for
-                the SDK health check).
+            grpc_port: Sidecar gRPC port.
+            http_port: Sidecar HTTP port (also used for the SDK health check).
             app_port: Port the app listens on (implies ``--app-protocol grpc``).
             app_cmd: Shell command to start alongside the sidecar.
             components: Path to component YAML directory.  Defaults to
@@ -85,9 +85,12 @@ def start_sidecar(
         # check starts hitting the HTTP endpoint.
         time.sleep(wait)
 
-        # DaprClient constructor calls DaprHealth.wait_for_sidecar(), which
-        # polls http://localhost:{DAPR_HTTP_PORT}/v1.0/healthz/outbound until
-        # the sidecar is ready (up to DAPR_HEALTH_TIMEOUT seconds).
+        # Point the SDK health check at the actual sidecar HTTP port.
+        # DaprHealth.wait_for_sidecar() reads settings.DAPR_HTTP_PORT, which
+        # is initialized once at import time and won't reflect a non-default
+        # http_port unless we update it here.
+        settings.DAPR_HTTP_PORT = http_port
+
         client = DaprClient(address=f'127.0.0.1:{grpc_port}')
         self._clients.append(client)
         return client

tests/integration/test_configuration.py

@@ -16,8 +16,7 @@ def _redis_set(key: str, value: str, version: int = 1) -> None:
     Dapr's Redis configuration store encodes values as ``value||version``.
     """
     subprocess.run(
-        f'docker exec {REDIS_CONTAINER} redis-cli SET {key} "{value}||{version}"',
-        shell=True,
+        args=('docker', 'exec', REDIS_CONTAINER, 'redis-cli', 'SET', key, f'"{value}||{version}"'),
         check=True,
         capture_output=True,
     )