@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-design/topics/testing.md

@@ -0,0 +1,437 @@
+# Testing Temporal Workflows
+
+> **Example:** [`testing.twf`](./testing.twf)
+
+Strategies for testing workflows, activities, and ensuring determinism.
+
+## Testing Pyramid for Temporal
+
+```text
+         ┌─────────────────┐
+         │   End-to-End    │  Few, slow, high confidence
+         │    Tests        │
+         ├─────────────────┤
+         │  Integration    │  Test with real services
+         │    Tests        │
+         ├─────────────────┤
+         │   Workflow      │  Mock activities
+         │  Unit Tests     │
+         ├─────────────────┤
+         │   Activity      │  Mock clients/SDKs
+         │  Unit Tests     │
+         └─────────────────┘  Many, fast, isolated
+```
+
+---
+
+## Activity Unit Testing
+
+Test activities in isolation by mocking external dependencies.
+
+### Pattern
+
+> Note: Activity body implementations and test assertions are SDK-level code, not TWF notation.
+
+```pseudo
+# Activity implementation
+activity ProcessPayment(payment: Payment) -> PaymentResult:
+    # Validate
+    if payment.amount <= 0:
+        raise InvalidPaymentError("Amount must be positive")
+    
+    # Call external service
+    result = paymentClient.charge(payment)
+    
+    return PaymentResult{
+        transactionId: result.id,
+        status: result.status
+    }
+
+# Test
+test "ProcessPayment succeeds with valid payment":
+    mockPaymentClient = Mock()
+    mockPaymentClient.charge.returns({id: "txn-123", status: "success"})
+    
+    result = ProcessPayment(Payment{amount: 100, cardId: "card-1"})
+    
+    assert result.transactionId == "txn-123"
+    assert result.status == "success"
+    assert mockPaymentClient.charge.called_with(Payment{amount: 100})
+
+test "ProcessPayment fails with invalid amount":
+    expect_error InvalidPaymentError:
+        ProcessPayment(Payment{amount: -50})
+```
+
+### What to Test in Activities
+- Input validation
+- Error handling for external failures
+- Correct client/SDK usage
+- Return value construction
+
+---
+
+## Workflow Unit Testing
+
+Test workflow logic by mocking activities. Use Temporal's test framework.
+
+### Pattern
+
+```twf
+workflow RenewalProcessing(renewal: Renewal) -> (RenewalResult):
+    activity ValidateRenewalRequest(renewal) -> validated
+    if not validated.success:
+        close fail(RenewalResult{status: "invalid"})
+
+    activity ChargeRenewalPayment(renewal.payment) -> payment
+    activity ActivateRenewedPlan(renewal)
+
+    close complete(RenewalResult{status: "completed", paymentId: payment.id})
+```
+
+```pseudo
+# Test
+test "RenewalProcessing completes successfully":
+    env = TestWorkflowEnvironment()
+    
+    # Mock activities
+    env.mock_activity(ValidateRenewalRequest, returns: {success: true})
+    env.mock_activity(ChargeRenewalPayment, returns: {id: "pay-123"})
+    env.mock_activity(ActivateRenewedPlan, returns: {})
+    
+    # Execute workflow
+    result = env.execute_workflow(RenewalProcessing, Renewal{id: "renew-1"})
+    
+    # Assert result
+    assert result.status == "completed"
+    assert result.paymentId == "pay-123"
+    
+    # Assert activity calls
+    assert env.activity_called(ValidateRenewalRequest, with: Renewal{id: "renew-1"})
+    assert env.activity_called(ChargeRenewalPayment)
+    assert env.activity_called(ActivateRenewedPlan)
+
+test "RenewalProcessing returns invalid for failed validation":
+    env = TestWorkflowEnvironment()
+    
+    env.mock_activity(ValidateRenewalRequest, returns: {success: false, error: "bad renewal"})
+    
+    result = env.execute_workflow(RenewalProcessing, Renewal{id: "renew-1"})
+    
+    assert result.status == "invalid"
+    assert not env.activity_called(ChargeRenewalPayment)   # Not called
+    assert not env.activity_called(ActivateRenewedPlan)    # Not called
+```
+
+### What to Test in Workflows
+- Activity call ordering
+- Conditional logic (correct branch taken)
+- Error handling (activity failures)
+- Signal/query handlers
+- Timeout behavior
+
+---
+
+## Replay Testing (Determinism Verification)
+
+Verify workflows are deterministic by replaying against recorded history.
+
+### Why Replay Testing
+
+```text
+Version 1: Workflow runs, generates history
+Version 2: Workflow code changes
+Replay Test: Run version 2 against version 1 history
+Result: PASS (deterministic) or FAIL (non-determinism detected)
+```
+
+### Pattern
+
+```pseudo
+# Record workflow history
+test "record RenewalProcessing history":
+    env = TestWorkflowEnvironment()
+    # ... execute workflow ...
+    history = env.get_workflow_history()
+    save_to_file("renewal_processing_v1.history", history)
+
+# Replay test
+test "RenewalProcessing replays deterministically":
+    history = load_from_file("renewal_processing_v1.history")
+    
+    env = TestWorkflowEnvironment()
+    result = env.replay_workflow(RenewalProcessing, history)
+    
+    assert result.replay_successful
+    assert not result.non_determinism_errors
+```
+
+### Maintaining History Files
+- Store history files in version control
+- Update when workflow signature changes
+- Keep multiple versions for migration testing
+
+---
+
+## Testing Signals and Queries
+
+### Signal Testing
+
+```twf
+workflow LeaveRequestApproval(request: LeaveRequest) -> (Decision):
+    await one:
+        signal Approved:
+            close complete(Decision{status: "approved"})
+        signal Rejected:
+            close complete(Decision{status: "rejected"})
+        timer(1h):
+            close complete(Decision{status: "timeout"})
+```
+
+```pseudo
+# Test
+test "LeaveRequestApproval handles Approved signal":
+    env = TestWorkflowEnvironment()
+    
+    # Start workflow
+    handle = env.start_workflow(LeaveRequestApproval, LeaveRequest{id: "req-1"})
+    
+    # Send signal
+    env.signal_workflow(handle, Approved, {approver: "alice"})
+    
+    # Get result
+    result = env.get_workflow_result(handle)
+    assert result.status == "approved"
+
+test "LeaveRequestApproval handles timeout":
+    env = TestWorkflowEnvironment()
+    
+    handle = env.start_workflow(LeaveRequestApproval, LeaveRequest{id: "req-1"})
+    
+    # Skip time forward
+    env.skip_time(2h)
+    
+    result = env.get_workflow_result(handle)
+    assert result.status == "timeout"  # or however timeout is handled
+```
+
+### Query Testing
+
+```twf
+workflow StatusWorkflow(orderId: string) -> (OrderResult):
+    query GetStatus() -> (string):
+        return status
+
+    status = "pending"
+    activity StartProcessing(orderId)
+
+    status = "processing"
+    activity ProcessItems(orderId)
+
+    status = "completed"
+    close complete(OrderResult{status: status, orderId: orderId})
+```
+
+```pseudo
+# Test
+test "GetStatus query returns current status":
+    env = TestWorkflowEnvironment()
+    
+    # Mock activity to block
+    blocker = env.mock_activity(ProcessItems, blocks: true)
+    
+    handle = env.start_workflow(StatusWorkflow, "order-1")
+    
+    # Query while processing
+    status = env.query_workflow(handle, GetStatus)
+    assert status == "processing"
+    
+    # Unblock activity
+    blocker.unblock({})
+    
+    # Query after completion
+    env.wait_for_workflow(handle)
+    status = env.query_workflow(handle, GetStatus)
+    assert status == "completed"
+```
+
+---
+
+## Testing Timers
+
+Use time-skipping to test timer behavior without waiting.
+
+```twf
+workflow ReminderWorkflow(userId: string):
+    activity SendFirstReminder(userId)
+
+    await timer(24h)
+
+    activity SendSecondReminder(userId)
+
+    await timer(48h)
+
+    activity SendFinalReminder(userId)
+```
+
+```pseudo
+# Test
+test "ReminderWorkflow sends reminders at correct intervals":
+    env = TestWorkflowEnvironment()
+    
+    env.mock_activity(SendFirstReminder, returns: {})
+    env.mock_activity(SendSecondReminder, returns: {})
+    env.mock_activity(SendFinalReminder, returns: {})
+    
+    handle = env.start_workflow(ReminderWorkflow, "user-1")
+    
+    # First reminder sent immediately
+    assert env.activity_called(SendFirstReminder)
+    assert not env.activity_called(SendSecondReminder)
+    
+    # Skip 24 hours
+    env.skip_time(24h)
+    
+    assert env.activity_called(SendSecondReminder)
+    assert not env.activity_called(SendFinalReminder)
+    
+    # Skip 48 more hours
+    env.skip_time(48h)
+    
+    assert env.activity_called(SendFinalReminder)
+```
+
+---
+
+## Testing Child Workflows
+
+```twf
+workflow ParentWorkflow(data: Data) -> (Result):
+    workflow ChildWorkflow(data.item) -> childResult
+    close complete(Result{childData: childResult})
+
+workflow ChildWorkflow(item: Item) -> (ChildResult):
+    activity ProcessItem(item)
+    close complete(ChildResult{processed: true})
+```
+
+```pseudo
+# Test parent in isolation
+test "ParentWorkflow calls child correctly":
+    env = TestWorkflowEnvironment()
+    
+    env.mock_child_workflow(ChildWorkflow, returns: {processed: true})
+    
+    result = env.execute_workflow(ParentWorkflow, Data{item: Item{id: "1"}})
+    
+    assert result.childData.processed == true
+    assert env.child_workflow_called(ChildWorkflow, with: Item{id: "1"})
+
+# Test parent and child together
+test "ParentWorkflow integration with ChildWorkflow":
+    env = TestWorkflowEnvironment()
+    
+    # Mock only activities, let child workflow run
+    env.mock_activity(ProcessItem, returns: {})
+    
+    result = env.execute_workflow(ParentWorkflow, Data{item: Item{id: "1"}})
+    
+    assert result.childData.processed == true
+```
+
+---
+
+## Integration Testing
+
+Test with real Temporal server (local or test cluster).
+
+### Setup
+
+```bash
+# Start local Temporal for testing
+temporal server start-dev
+
+# Or use testcontainers
+test_environment = TemporalTestContainer()
+test_environment.start()
+```
+
+### Pattern
+
+```pseudo
+test "RenewalProcessing end-to-end":
+    # Use real Temporal client
+    client = TemporalClient(address: "localhost:7233")
+    
+    # Start real worker
+    worker = Worker(
+        client: client,
+        task_queue: "test-queue",
+        workflows: [RenewalProcessing],
+        activities: [ValidateRenewalRequest, ChargeRenewalPayment, ActivateRenewedPlan]
+    )
+    worker.start_async()
+    
+    # Execute workflow
+    handle = client.start_workflow(
+        RenewalProcessing,
+        Renewal{id: "test-renew-1"},
+        workflow_id: "test-renew-1"
+    )
+    
+    # Wait for result
+    result = handle.result(timeout: 30s)
+    
+    assert result.status == "completed"
+    
+    # Cleanup
+    worker.stop()
+```
+
+---
+
+## Testing Best Practices
+
+### Do's
+
+| Practice | Rationale |
+|----------|-----------|
+| Mock activities in workflow tests | Isolate workflow logic |
+| Use replay tests | Catch non-determinism early |
+| Test failure paths | Verify error handling |
+| Use time-skipping | Fast timer tests |
+| Test signal ordering | Validate async behavior |
+
+### Don'ts
+
+| Anti-Pattern | Problem |
+|--------------|---------|
+| Testing deterministic logic via integration tests | Slow, flaky |
+| Skipping replay tests | Non-determinism in production |
+| Mocking workflow internals | Brittle tests |
+| Real time waits | Slow tests |
+| Testing Temporal internals | Not your responsibility |
+
+---
+
+## Test Coverage Checklist
+
+### Activity
+- [ ] Valid inputs produce correct output
+- [ ] Invalid inputs produce appropriate errors
+- [ ] External service failures handled
+- [ ] Retryable vs non-retryable errors classified
+
+### Workflow
+- [ ] Happy path completes successfully
+- [ ] Each conditional branch tested
+- [ ] Activity failures handled correctly
+- [ ] Signals processed correctly
+- [ ] Queries return correct state
+- [ ] Timeouts handled appropriately
+- [ ] Replay test passes
+
+### Integration
+- [ ] End-to-end happy path
+- [ ] Cross-service communication
+- [ ] Failure recovery

package/skills/temporal-architect-design/topics/testing.twf

@@ -0,0 +1,177 @@
+# Source: testing.md
+# Patterns: simple testable workflow/activity pairs
+# Domain: subscription renewals + leave-of-absence approvals + reminder cadences
+#         + status-tracked status flow + condition-driven subscription manager.
+# Each workflow is intentionally small and isolated so unit tests can drive
+# signals/updates and assert on activity calls in isolation.
+
+# --- Basic linear workflow: renewal processing ---
+
+workflow RenewalProcessing(renewal: Renewal) -> (RenewalResult):
+    activity ValidateRenewalRequest(renewal) -> validated
+    if (validated.success == false):
+        close fail(RenewalResult{status: "invalid"})
+
+    activity ChargeRenewalPayment(renewal.payment) -> payment
+    activity ActivateRenewedPlan(renewal)
+
+    close complete(RenewalResult{status: "completed", paymentId: payment.id})
+
+# --- Workflow with timer: scheduled reminder cadence ---
+
+workflow ReminderWorkflow(userId: string):
+    activity SendFirstReminder(userId)
+
+    await timer(24h)
+
+    activity SendSecondReminder(userId)
+
+    await timer(48h)
+
+    activity SendFinalReminder(userId)
+    close complete
+
+# --- Workflow with signals: leave-of-absence approval ---
+
+workflow LeaveRequestApproval(request: LeaveRequest) -> (Decision):
+    signal Approved(approver: string):
+        approved = true
+        approverName = approver
+
+    signal Rejected(approver: string, reason: string):
+        rejected = true
+        rejectReason = reason
+
+    approved = false
+    rejected = false
+    approverName = ""
+    rejectReason = ""
+
+    activity NotifyManagers(request)
+
+    await one:
+        signal Approved:
+            close complete(Decision{status: "approved", approver: approverName})
+        signal Rejected:
+            close fail(Decision{status: "rejected", reason: rejectReason})
+        timer(1h):
+            close complete(Decision{status: "timeout"})
+
+# --- Workflow with query: status flow ---
+
+workflow StatusWorkflow(orderId: string) -> (OrderResult):
+    query GetStatus() -> (string):
+        return status
+
+    status = "pending"
+    activity StartProcessing(orderId)
+
+    status = "processing"
+    activity ProcessItems(orderId)
+
+    status = "completed"
+    close complete(OrderResult{status: status, orderId: orderId})
+
+# --- Complex workflow for testing continue-as-new, conditions, and updates ---
+
+workflow SubscriptionManager(userId: string, sub: Subscription):
+    state:
+        condition renewed
+
+    update RenewSubscription(payment: Payment) -> (RenewResult):
+        activity ValidatePayment(payment) -> validation
+        if (validation.ok):
+            set renewed
+            return RenewResult{accepted: true}
+        else:
+            return RenewResult{accepted: false, reason: validation.error}
+
+    query GetSubscription() -> (Subscription):
+        return sub
+
+    for:
+        # Wait for renewal or expiration
+        await one:
+            renewed:
+                activity ExtendSubscription(userId, sub) -> sub
+                unset renewed
+            timer(30d):
+                activity SendExpirationWarning(userId)
+                await one:
+                    renewed:
+                        activity ExtendSubscription(userId, sub) -> sub
+                        unset renewed
+                    timer(7d):
+                        activity CancelSubscription(userId)
+                        close complete
+
+        # Periodic state snapshot for continue-as-new
+        close continue_as_new(userId, sub)
+
+# --- Supporting activities ---
+
+activity ValidateRenewalRequest(renewal: Renewal) -> (ValidationResult):
+    return validate(renewal)
+
+activity ChargeRenewalPayment(payment: Payment) -> (PaymentResult):
+    return charge(payment)
+
+activity ActivateRenewedPlan(renewal: Renewal):
+    activate(renewal)
+
+activity SendFirstReminder(userId: string):
+    remind(userId, "first")
+
+activity SendSecondReminder(userId: string):
+    remind(userId, "second")
+
+activity SendFinalReminder(userId: string):
+    remind(userId, "final")
+
+activity NotifyManagers(request: LeaveRequest):
+    notify(request.managers)
+
+activity StartProcessing(orderId: string):
+    start(orderId)
+
+activity ProcessItems(orderId: string):
+    process(orderId)
+
+activity ValidatePayment(payment: Payment) -> (PaymentValidation):
+    return validate(payment)
+
+activity ExtendSubscription(userId: string, sub: Subscription) -> (Subscription):
+    return extend(userId, sub)
+
+activity SendExpirationWarning(userId: string):
+    warn(userId)
+
+activity CancelSubscription(userId: string):
+    cancel(userId)
+
+# --- Worker and namespace ---
+
+worker testingWorker:
+    workflow RenewalProcessing
+    workflow ReminderWorkflow
+    workflow LeaveRequestApproval
+    workflow StatusWorkflow
+    workflow SubscriptionManager
+    activity ValidateRenewalRequest
+    activity ChargeRenewalPayment
+    activity ActivateRenewedPlan
+    activity SendFirstReminder
+    activity SendSecondReminder
+    activity SendFinalReminder
+    activity NotifyManagers
+    activity StartProcessing
+    activity ProcessItems
+    activity ValidatePayment
+    activity ExtendSubscription
+    activity SendExpirationWarning
+    activity CancelSubscription
+
+namespace testing:
+    worker testingWorker
+        options:
+            task_queue: "testing"