port of behaviour testing

Author: prassanna-ravishankar

examples/tutorials/20_behavior_testing/000_basic_sync_testing/README.md

@@ -0,0 +1,97 @@
+# Tutorial 20.0: Basic Sync Agent Testing
+
+Learn how to write automated tests for sync agents using the AgentEx testing framework.
+
+## What You'll Build
+
+Automated tests for sync agents that verify:
+- Basic response capability
+- Multi-turn conversation
+- Context maintenance
+- Response content validation
+
+## Prerequisites
+
+- AgentEx services running (`make dev`)
+- A sync agent running (Tutorial 00_sync/000_hello_acp recommended)
+
+## Quick Start
+
+Run the tests:
+```bash
+pytest test_sync_agent.py -v
+```
+
+## Understanding Sync Agent Testing
+
+Sync agents respond **immediately** via the `send_message()` API. Testing them is straightforward:
+
+```python
+from agentex.lib.testing import test_sync_agent
+
+def test_basic_response():
+    with test_sync_agent() as test:
+        response = test.send_message("Hello!")
+        assert response is not None
+```
+
+## The Test Helper: `test_sync_agent()`
+
+The `test_sync_agent()` context manager:
+1. Connects to AgentEx
+2. Finds a sync agent
+3. Creates a test task
+4. Returns a `SyncAgentTest` helper
+5. Automatically cleans up the task when done
+
+## Key Methods
+
+### `send_message(content: str) -> TextContent`
+Send a message and get immediate response (no async/await).
+
+### `get_conversation_history() -> list[TextContent]`
+Get all messages exchanged in the test session.
+
+## Common Assertions
+
+```python
+from agentex.lib.testing import (
+    assert_valid_agent_response,
+    assert_agent_response_contains,
+    assert_conversation_maintains_context,
+)
+
+# Response is valid
+assert_valid_agent_response(response)
+
+# Response contains specific text
+assert_agent_response_contains(response, "hello")
+
+# Agent maintains context
+test.send_message("My name is Alice")
+test.send_message("What's my name?")
+history = test.get_conversation_history()
+assert_conversation_maintains_context(history, ["Alice"])
+```
+
+## Test Pattern
+
+A typical sync agent test follows this pattern:
+
+1. **Setup** - `with test_sync_agent() as test:`
+2. **Action** - `response = test.send_message("...")`
+3. **Assert** - Validate response
+4. **Cleanup** - Automatic when context manager exits
+
+## Tips
+
+- Tests skip gracefully if AgentEx isn't running
+- Each test gets a fresh task (isolated)
+- Conversation history tracks all exchanges
+- Use descriptive test names that explain what behavior you're testing
+
+## Next Steps
+
+- Complete Tutorial 20.1 for agentic agent testing
+- Apply these patterns to test your own agents
+- Integrate tests into your development workflow

examples/tutorials/20_behavior_testing/000_basic_sync_testing/test_sync_agent.py

@@ -0,0 +1,103 @@
+"""
+Tutorial 20.0: Basic Sync Agent Testing
+
+This tutorial demonstrates how to test sync agents using the agentex.lib.testing framework.
+
+Prerequisites:
+    - AgentEx services running (make dev)
+    - A sync agent running (e.g., tutorial 00_sync/000_hello_acp)
+
+Run:
+    pytest test_sync_agent.py -v
+"""
+
+from agentex.lib.testing import (
+    assert_agent_response_contains,
+    assert_conversation_maintains_context,
+    assert_valid_agent_response,
+    test_sync_agent,
+)
+
+
+def test_sync_agent_responds():
+    """Test that sync agent responds to a simple message."""
+    with test_sync_agent() as test:
+        # Send a message
+        response = test.send_message("Hello! How are you?")
+
+        # Verify we got a valid response
+        assert_valid_agent_response(response)
+        print(f"✓ Agent responded: {response.content[:50]}...")
+
+
+def test_sync_agent_multi_turn():
+    """Test that sync agent handles multi-turn conversation."""
+    with test_sync_agent() as test:
+        # First exchange
+        response1 = test.send_message("Hello!")
+        assert_valid_agent_response(response1)
+
+        # Second exchange
+        response2 = test.send_message("Can you help me with something?")
+        assert_valid_agent_response(response2)
+
+        # Third exchange
+        response3 = test.send_message("Thank you!")
+        assert_valid_agent_response(response3)
+
+        # Verify conversation history
+        history = test.get_conversation_history()
+        assert len(history) >= 6  # 3 user + 3 agent messages
+        print(f"✓ Completed {len(history)} message conversation")
+
+
+def test_sync_agent_context():
+    """Test that sync agent maintains conversation context."""
+    with test_sync_agent() as test:
+        # Establish context
+        response1 = test.send_message("My name is Sarah and I'm a teacher")
+        assert_valid_agent_response(response1)
+
+        # Query the context
+        response2 = test.send_message("What is my name?")
+        assert_valid_agent_response(response2)
+
+        # Check context is maintained (agent should mention Sarah)
+        history = test.get_conversation_history()
+        assert_conversation_maintains_context(history, ["Sarah"])
+        print("✓ Agent maintained conversation context")
+
+
+def test_sync_agent_specific_content():
+    """Test that agent responds with expected content."""
+    with test_sync_agent() as test:
+        # Ask a factual question
+        response = test.send_message("What is 2 plus 2?")
+
+        # Verify response is valid
+        assert_valid_agent_response(response)
+
+        # Verify response contains expected content
+        # (This assumes the agent can do basic math)
+        assert_agent_response_contains(response, "4")
+        print(f"✓ Agent provided correct answer: {response.content[:50]}...")
+
+
+def test_sync_agent_conversation_length():
+    """Test conversation history tracking."""
+    with test_sync_agent() as test:
+        # Send 3 messages
+        test.send_message("First message")
+        test.send_message("Second message")
+        test.send_message("Third message")
+
+        # Get history
+        history = test.get_conversation_history()
+
+        # Should have 6 messages: 3 user + 3 agent
+        assert len(history) >= 6, f"Expected >= 6 messages, got {len(history)}"
+        print(f"✓ Conversation history contains {len(history)} messages")
+
+
+if __name__ == "__main__":
+    print("Run with: pytest test_sync_agent.py -v")

examples/tutorials/20_behavior_testing/010_agentic_testing/README.md

@@ -0,0 +1,112 @@
+# Tutorial 20.1: Agentic Agent Testing
+
+Learn how to test agentic agents that use event-driven architecture and require polling.
+
+## What You'll Learn
+
+- How agentic agent testing differs from sync testing
+- Using async context managers for testing
+- Configuring timeouts for polling
+- Testing event-driven behavior
+
+## Prerequisites
+
+- AgentEx services running (`make dev`)
+- An agentic agent running (Tutorial 10_agentic recommended)
+- Understanding of async/await in Python
+
+## Quick Start
+
+Run the tests:
+```bash
+pytest test_agentic_agent.py -v
+```
+
+## Key Differences from Sync Testing
+
+| Aspect | Sync Testing | Agentic Testing |
+|--------|-------------|-----------------|
+| Response | Immediate | Requires polling |
+| Method | `send_message()` | `send_event()` |
+| Context manager | Sync (`with`) | Async (`async with`) |
+| Test function | Regular function | `@pytest.mark.asyncio` |
+| Timeout | N/A | Configure per request |
+
+## The Agentic Test Helper
+
+```python
+import pytest
+from agentex.lib.testing import test_agentic_agent
+
+@pytest.mark.asyncio
+async def test_my_agent():
+    async with test_agentic_agent() as test:
+        # Send event and wait for response
+        response = await test.send_event("Hello!", timeout_seconds=15.0)
+        assert response is not None
+```
+
+## Understanding Timeouts
+
+Agentic agents process events asynchronously, so you need to:
+1. Send the event
+2. Poll for the response
+3. Wait up to `timeout_seconds`
+
+**Default timeout**: 15 seconds
+**Recommended timeout**: 20-30 seconds for complex operations
+
+If the agent doesn't respond within the timeout, you'll get a `RuntimeError` with diagnostic information.
+
+## Testing Patterns
+
+### Basic Response
+```python
+@pytest.mark.asyncio
+async def test_agentic_responds():
+    async with test_agentic_agent() as test:
+        response = await test.send_event("Hello!", timeout_seconds=15.0)
+        assert_valid_agent_response(response)
+```
+
+### Multi-Turn Conversation
+```python
+@pytest.mark.asyncio
+async def test_conversation():
+    async with test_agentic_agent() as test:
+        r1 = await test.send_event("My name is Alex", timeout_seconds=15.0)
+        r2 = await test.send_event("What's my name?", timeout_seconds=15.0)
+
+        history = await test.get_conversation_history()
+        assert len(history) >= 2
+```
+
+### Long-Running Operations
+```python
+@pytest.mark.asyncio
+async def test_complex_task():
+    async with test_agentic_agent() as test:
+        # Some agents need more time for complex work
+        response = await test.send_event(
+            "Analyze this data...",
+            timeout_seconds=30.0  # Longer timeout
+        )
+        assert response is not None
+```
+
+## Troubleshooting
+
+**TimeoutError**: Agent didn't respond in time
+- Increase `timeout_seconds`
+- Check agent is running
+- Check AgentEx logs for errors
+
+**No agentic agents available**:
+- Run an agentic tutorial agent first
+- Check `await client.agents.list()` shows agentic agents
+
+## Next Steps
+
+- Test your own agentic agents
+- Explore temporal agent testing for workflow-based agents
+- Integrate behavior tests into CI/CD